I agree that our internal processing can conflict with user icons. This should be avoided and we have two ways to do this

1. Distinguishing between internal and user icons (your proposal)
2. Defining a set of rules how icons should be provided and may be post-processed.

I'd prefer to have a closer look at 2 first. Users might want to opt into our features like choosing high-res images and adapting color according to the theme. In general, it would be a good idea to explicitly document what users should provide as icon. I suppose we don't have more than saying you can add an icon file. https://matplotlib.org/devdocs/api/backend_bases_api.html#matplotlib.backend_bases.ToolContainerBase.add_toolitem

We should specify

• size(s)
• formats (at least explicitly mention common ones, not necessary list every format supported by every GUI framework)
• Color adjustment; To be discussed: Maybe limit this to the case of only black-on-transparent icons? - We should be able to check this.
• ...

Only if we then think that we still need an explicit flag for user icons, we should follow up on that.

I need to experiment a bit more, but I believe GTK4 doesn't correctly theme icons because we are not following the icon theme spec directory layout. If that is the case and I can't figure out a way around that, then I think we should a) move icons to corresponding directories, and b) say that is how we expect user-provided icons to work.