Skip to content

[docs][material-icons] Improve icon search with generated keywords and descriptions - #49204

Draft
Janpot wants to merge 10 commits into
mui:masterfrom
Janpot:docs/icon-descriptions
Draft

Janpot wants to merge 10 commits into
mui:masterfrom
Janpot:docs/icon-descriptions

Conversation

@Janpot

@Janpot Janpot commented Sep 24, 2026 •

Copy link
Copy Markdown
Member

The icon search only knows an icon's name and the tags from Google's Material Symbols metadata. Searches for everyday names ("cog", "kebab menu", "dustbin") or for what an icon looks like ("eye with slash", "check in circle", "funnel") often return nothing or rank the right icon far down.

This adds iconDescriptions.json with, for every icon, extra search keywords and a one-sentence visual description. pnpm docs:mdicons:synonyms now merges those words into synonyms.js the same way it merges Google's tags, so the search page itself does not change.

Notes for reviewers:

  • The JSON is generated by an LLM looking at rendered icons, not written by hand. The workflow is in the icon-descriptions skill (.agents/skills/icon-descriptions), with docs/scripts/iconDescriptions.mjs rendering the icon sheets and validating and merging the output. Running the skill again only processes icons that are missing from the JSON, so it can be rerun when icons are added.
  • docs:mdicons:synonyms was broken on master: it imported LEGACY_OUTLINE_ICONS from builder.test.mjs, which now imports Vitest and fails under babel-node. The list moved to packages/mui-icons-material/legacyOutlineIcons.mjs.
  • Running the script also picked up new tags from Google's current metadata for 26 icons.
  • Descriptions avoid words like "filled" or "outline" because one description covers all five icon styles.
  • On a set of hand-written test queries, the right icon is in the top 10 for 19 of 22 appearance queries (8 today) and 33 of 40 meaning queries (32 today). It is ranked first less often for meaning queries (14 vs 18), because the extra words are sorted in with the existing ones and flexsearch favors earlier words. [docs][material-icons] Prototype semantic icon search with static embeddings #49205 addresses ranking.

@code-infra-dashboard

code-infra-dashboard Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Deploy preview

Bundle size

Bundle Parsed size Gzip size
@mui/material 0B(0.00%) 0B(0.00%)
@mui/lab 0B(0.00%) 0B(0.00%)
@mui/private-theming 0B(0.00%) 0B(0.00%)
@mui/system 0B(0.00%) 0B(0.00%)
@mui/utils 0B(0.00%) 0B(0.00%)

Details of bundle changes


Check out the code infra dashboard for more information about this PR.

@Janpot Janpot added scope: icons Changes related to the icons. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. needs cherry-pick The PR should be cherry-picked to master after merge. v9.x labels Sep 24, 2026
@github-actions github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Sep 25, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs cherry-pick The PR should be cherry-picked to master after merge. PR: out-of-date The pull request has merge conflicts and can't be merged. scope: icons Changes related to the icons. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. v9.x

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant