Material Icons

Use official Material Symbols by default. Use classic Material Icons only when the project already uses them, requires two-tone, or explicitly asks for them.

Workflow

1. Detect the target environment before choosing an integration path: Android Compose, Android Views/XML, Flutter, web, or native SVG framework. Reuse its existing local-asset conventions and established icon style where possible.
2. Extract filters from the request. Ask one concise question only if the intended action is ambiguous. Infer outlined, 24 px, and accessible labels when omitted.
3. Search names with scripts/search_material_symbols.py for reproducible candidates. If a visual or semantic decision is important, verify shortlisted candidates at Google Fonts Icons.
4. Return or use 2-4 candidates with their exact symbol names. Prefer the most literal, familiar action over a metaphor.
5. Integrate only the selected icon. Do not add a global font or an entire icon bundle when a single SVG/vector asset is sufficient.
6. Add an accessible label for interactive icons; use a null/decorative label only where the icon is explicitly redundant to adjacent text.
7. Read material-icons-policy.json at the repository root before asking configuration questions. Create it only with user approval, using scripts/project_icon_policy.py init.
8. Detect the language of the user's prompt. Formulate all questions, suggestions, choice options, and answers exclusively in that language. Do not output slash-separated bilingual text (e.g. "English / Russian").

Filters and selection

Accept meaning, platform, set, style, fill, weight, grade, opticalSize, size, color, format, and accessibilityLabel.

• set: default Material Symbols; Material Icons is legacy and has no new icons.
• style: outlined (default), rounded, or sharp.
• fill: Symbols support 0 to 100; use filled states sparingly to indicate selection or a saved state.
• weight: 100 to 700, default 400. grade: -50 to 200, default 0. opticalSize: 20 to 48, default 24.
• Prefer 20 or 24 px if pixel-grid crispness matters.
• Avoid using Material Symbols for third-party brand logos; use the brand's approved assets instead.

Selection states and navigation

For bottom navigation, tab bars, and comparable persistent navigation, identify whether the project needs selected and unselected variants. When the user did not specify, ask: “Should I prepare an outlined icon for unselected items and a filled variant for the selected item?”

Keep the same symbol metaphor across states: use the same Material Symbol with FILL 0/1 where the platform supports it, or matching outlined/filled local assets. Do not automatically create both variants for a one-off icon, destructive action, or when the existing design system uses one style only.

Search

Run from this skill folder or pass the absolute script path:

python scripts/search_material_symbols.py "save bookmark" --style rounded --limit 5
python scripts/search_material_symbols.py "account settings" --json

The script downloads and caches the official repository tree, ranks exact names and token matches, and emits an official Google Fonts URL plus source locations. Treat its ranking as a shortlist, not proof of semantic equivalence.

No exact match

Never invent an icon name or present an approximate icon as an exact match. If research cannot establish a suitable symbol:

1. Pick the least misleading available alternative only when the user asked to proceed without approval.
2. Add a concise, searchable TODO beside the use site, for example // TODO(material-icons): replace ic_help_outline when an exact "<requested meaning>" symbol is available.
3. In the handoff, list every requested meaning that had no suitable official symbol, the temporary symbol used, and why it is only approximate.
4. If the fallback could alter meaning or cause a harmful action, stop and ask the user to choose; do not add it automatically.

Project policy, import, and audit

Use material-icons-policy.json to retain the Compose decision, local asset directories, default style, and default size across tasks. Never overwrite it without explicit permission.

python scripts/project_icon_policy.py init --root <project>
python scripts/import_material_symbol.py bookmark --style rounded --target android --root <project>
python scripts/import_material_symbol.py bookmark --target flutter --root <project> --register-flutter-asset
python scripts/audit_icon_assets.py --root <project>
python scripts/preview_material_symbols.py bookmark bookmark_add collections_bookmark --style rounded

The importer never overwrites an existing asset. For Android it downloads Google's official VectorDrawable XML directly; for Flutter/web it downloads the official SVG. Before adding flutter_svg, obtain the user's approval unless it is already a project dependency.

Use agent_features.py detect before integrating into an unfamiliar project. Use agent_features.py migrate --root <project> for a Compose migration report, import every reported drawable, then use --apply only after review. agent_features.py validate checks likely missing accessibility labels.

When creating or initializing a new material-icons-policy.json file for the project, ask the user to choose the default icon style, default icon size, and optional features. Detect the user's language and present the questions and choices exclusively in that language.

Example templates:

• English:
  • Question 1 (Default Style): "What visual style of Material Symbols should be the default for this project?"
    • Option 1: "Outlined (recommended default)"
    • Option 2: "Rounded"
    • Option 3: "Sharp"
  • Question 2 (Default Size): "What should be the default icon size (in pixels)?"
    • Option 1: "24 px (recommended default)"
    • Option 2: "20 px (compact)"
    • Option 3: "Other (specify)"
  • Question 3 (Optional Features): "Would you like to enable any of the following optional features?"
    • Option 1: "Generate code wrappers (constants) for imported icons (generateWrappers)"
    • Option 2: "Enable offline catalog for offline search (offlineCatalog)"
    • Option 3: "Keep both disabled (default)"
• Russian:
  • Question 1 (Стиль по умолчанию): "Какой визуальный стиль Material Symbols сделать стилем по умолчанию для этого проекта?"
    • Option 1: "Outlined / Контурный (рекомендуется по умолчанию)"
    • Option 2: "Rounded / Скругленный"
    • Option 3: "Sharp / Острый"
  • Question 2 (Размер по умолчанию): "Какой размер иконок (в пикселях) использовать по умолчанию?"
    • Option 1: "24 px (рекомендуется по умолчанию)"
    • Option 2: "20 px (компактный)"
    • Option 3: "Другой (указать свой)"
  • Question 3 (Дополнительные функции): "Хотите ли вы включить какие-либо из следующих дополнительных функций?"
    • Option 1: "Генерировать программные обертки (константы) для импортированных иконок (generateWrappers)"
    • Option 2: "Включить офлайн-каталог для поиска без интернета (offlineCatalog)"
    • Option 3: "Оставить обе функции выключенными (по умолчанию)"

When offlineCatalog is enabled, run python scripts/sync_offline_catalog.py --root <project> to create <project>/.material-icons/catalog.json. Refresh it deliberately; do not keep a large SVG mirror unless the user explicitly requests one.

For selected/saved/active states, prefer the same symbol with FILL 0/1 or its outlined/filled counterpart. Do not change the icon metaphor between states. Generate preview_material_symbols.py output when a user needs to choose among visually close candidates.

Android Compose policy only

This policy applies only to Android projects using Jetpack Compose. Do not show this question for Android Views/XML, Flutter, web, React, Vue, or other environments.

androidx.compose.material.icons is no longer recommended by Android's API reference. Prefer official Material Symbol SVGs imported as local vector drawables.

On the first Material-icon request for an Android Compose project in a conversation, if the user has not already chosen a policy, ask exactly once. Detect the language of the user's prompt and formulate the question and choice options exclusively in that language. Do not mix languages or output slash-separated translations (e.g. "English / Russian").

Example templates for the question:

• English:
  • Question: "Android no longer recommends androidx.compose.material.icons. For this project, should I import the selected official icons into res/drawable and use local resources, or keep using the Compose icon library?"
  • Option 1: "(Recommended) Import official icons into res/drawable and use local resources"
  • Option 2: "Keep using the Compose icon library"
• Russian:
  • Question: "Android больше не рекомендует использовать androidx.compose.material.icons. Для этого проекта импортировать выбранные официальные иконки в res/drawable и использовать локальные ресурсы, или продолжить использовать библиотеку иконок Compose?"
  • Option 1: "(Рекомендуется) Импортировать официальные иконки в res/drawable и использовать локальные ресурсы"
  • Option 2: "Продолжить использовать библиотеку иконок Compose"

Remember the answer for the rest of the conversation. Do not ask again if the repository clearly already has a documented project policy or the user selected one. If they choose the library, use it only for that project and report the tradeoff briefly.

Integration patterns

Use the project's existing library first. For a new web use of Symbols, link the required variable font and set axes deliberately:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" />
<span class="material-symbols-outlined" aria-hidden="true">bookmark</span>

.material-symbols-outlined {
  font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
}

For Android Compose with the local policy:

1. Download the selected official 24 px SVG; use the selected outlined, rounded, or sharp source path.
2. Import it with Android Studio New > Vector Asset > Local file (SVG), or convert it to a valid res/drawable/ic_<name>.xml vector drawable. Preserve viewportWidth, viewportHeight, and path data.
3. Use it with Icon(painterResource(R.drawable.ic_<name>), contentDescription = "…"). Keep a null content description only for a genuinely decorative icon.
4. Keep drawable names lowercase with underscores and avoid renaming an existing resource without updating every reference.

For Android Views/XML:

1. Download the selected official SVG and import it as res/drawable/ic_<name>.xml using Android Studio's Vector Asset importer or a valid VectorDrawable conversion.
2. Use it from XML with app:srcCompat="@drawable/ic_<name>" on AppCompat/ImageView-compatible views, or with android:src where the project's minimum SDK and view type support it.
3. Add android:contentDescription for actionable images. Use @null only for decorative images and preserve existing tint, state list, size, and click behavior.
4. Do not ask the Compose-library policy question: Android Views do not use androidx.compose.material.icons.

For Flutter:

1. Inspect pubspec.yaml and existing asset conventions. Prefer a local official SVG at assets/icons/<name>.svg for Material Symbols rather than assuming Flutter's built-in Icons contains the same symbol or variant.
2. Register newly added assets in pubspec.yaml. Reuse flutter_svg when it is already a dependency; otherwise ask before adding it, or use an existing project SVG renderer.
3. Render with the project's existing pattern, e.g. SvgPicture.asset('assets/icons/<name>.svg', semanticsLabel: '…'). Preserve width, height, color/tint, tap handler, and semantics.
4. Use an empty/excluded semantic label only for an icon that is genuinely decorative. Do not ask the Android Compose policy question for Flutter.

Migrate Compose icon library to local drawables

Use this workflow when the user asks to migrate androidx.compose.material.icons or the project policy switches to local assets:

1. Search imports and icon references, including Icons.Default.*, Icons.Outlined.*, Icons.Rounded.*, Icons.Sharp.*, and ImageVector.vectorResource.
2. Map each unique source icon to its exact Material Symbol name and requested visual style. Review names that are aliases or do not exist in Material Symbols; apply the no-exact-match policy.
3. Download/import each unique official SVG into res/drawable/ic_<symbol_name>.xml; deduplicate shared use sites.
4. Replace each Compose library vector with painterResource while preserving contentDescription, tint, size, modifiers, click behavior, and stateful filled/outlined semantics.
5. Remove androidx.compose.material:material-icons-extended and related imports only after no references remain. Do not remove base Material dependencies that the project still needs.
6. Report migrated icons, unresolved mappings, temporary TODO fallbacks, and deleted dependencies.

For React/Vue/native SVG usage, use the icon's official SVG from the repository and preserve its viewBox. Optimize only if the project pipeline already does so. For custom colors, use currentColor where that matches the project's conventions.

Licensing and reporting

Material symbols are Apache-2.0 licensed. State the exact name, set/style, and output path in the handoff. If no suitable icon exists, say so and offer the closest semantic alternatives rather than inventing an icon name.