Slightly unclear cause it's missing the general thing a 3D model is an example of.

I agree that this formulation is maybe not ideal. I was originally going to discuss things like STL-files, but since that is not the only way to represent a 3D model I kept it simple.

An option is to generate a static example loading an STL model (as we need additional libraries).

In what cases besides a 3D model would shading be useful?

I guess that one can have some other type of 3D polygons that are not necessarily considered to be a "3D model", although in some sense all 3D polygons could be considered a "3D model". One example may be voxels? Basically something that is not representing a physical object, but a visualization of something that happens to be 3D Polygons.

But I am open for suggestions.

Should we error out instead of warn? It seems to be incorrect usage, and I don’t see a reason why a user might want to set shade without having the results shaded.

The idea was that one can, sort of, expect the default colors to be used. However, those are currently not assigned until after the shading is applied. So I thought that a warning made more sense since this is something that can be changed in the future.

My point is

• If people use shade=True, they want shade. I see shade=True without giving colors as a plain usage error. IMHO it's better to fail loudly in that case rather than only warning and doing something else. - Warnings are often overlooked.
• Erroring out is the more narrow API. We can always do something else later without breaking backward-compatibility. OTOH when we fall back to non-shading. Doing something else later is a backward-incompatible change.

I think a note is more heavy than needed. We usually only state deprendencies between parameters in plain text:

Sure. Again this comes from the fact that ideally it should work without providing it, so I thought it was worth highlighting. But as it now errors as well, it is hard to miss it.