Ack, sorry I didn't qualify my issue w/ a "please don't try to implement this yet!" b/c I threw my suggestion out there to seed discussion. (ETA: but also thanks for liking the idea enough to try and implement it!)

Perhaps supporting (colorstring, alpha) pairs could be a solution

I was thinking of that, but to some extent that is the RGBA solution - maybe alpha can be obnoxiously explicit and also take a dict alpha={'facecolor': , edgecolor:' ', markerfacealt:} ? Granted, I think at that point then maybe it is the priority problem again - if the color is RGBA does it take precedence or alpha? Which granted is also currently a question if I pass in an RGBA and an alpha anyway

I have also been considering the dict-approach briefly. However, I don't think it's a good design. From the user point of view it's quite cumbersome to write facecolor='red', alpha={'facecolor': 0.5}. On the implementation side, we'd need special routing logic to apply the correct alpha key to the correct keyword. That may be somewhat automizable, but we have places where we can have "color or list of colors" and you'd need to fiddle alpha in that logic as well.

Conceptually, alpha is very closely related to color. Basically, you'll want to be able to make every color transparent. I think we should aim for a single entity that holds information on both. Some color specifications like RGBA already have that.

The formal way would be an explicit class Color('aquamarine', alpha=0.5). I think there were ideas at some point to introduce this internally as a way to standardize color handling.
The downside is that it's a bit more verbose when writing code and the user has to import that class. I could warm to the idea of having a tuple as a shortcut on the API side. color=('aquamarine', 0.5) is not too bad.

Granted, I think at that point then maybe it is the priority problem again - if the color is RGBA does it take precedence or alpha? Which granted is also currently a question if I pass in an RGBA and an alpha anyway

Currently, an explicit alpha overrides the alpha of a rgba tuple. (I think this is essentially a consequence of the semantics of to_rgba.) I think this is not particularly better or worse than the inverse semantics (having the alpha of rgba tuples win against explicit alphas), so we should just keep the current semantics in all cases.

Color('aquamarine', alpha=0.5)

So I never checked the signature of to_rgba(c, alpha) 🤦‍♀️ so maybe better documenting/adding an example would help.

On the one hand I'm very pro an explicit 'Color' type, and it would essentially be doing to_rgba under the hood, but on the other not sure if we wanna go down that route yet. (ETA @ksunden what are your thoughts?)

Maybe '(color, alpha)' is the most straightforward approach since it's basically a thin wrapper to calling to_rgba. Eta: also if me, Anthony, and Tim all sorta converged there, it'll be intuitive once it's advertised?

I think the way forward here is to declare ("red", 0.5) as an official way to define alpha for colors. We need to define that a bit more precise though: Should we allow this for the cases tuple and hex-string as well, which already have built-in alpha support? I'm inclined to not do this, which saves us extra checks and disambiguation.

Concrete steps:

• Define what we want to support
• Implement that in to_rgba (and _to_rgba_no_colorcycle) and in to_rgba_array
• Write tests for these functions
• Document the behavior in these functions as well as https://matplotlib.org/stable/tutorials/colors/colors.html

I assume everything else will fall in place then.

Should we allow this for the cases tuple and hex-string as well, which already have built-in alpha support? I'm inclined to not do this

My use case was HTML colors...I didn't know I could add alpha to them by concatenating an alpha value into hex until right now and I think "(anything considered a valid matplotlib color, alpha)" is more straighforward for the user than trying to special case a subset of the supported colors. Also, that is what's already supported in to_rgba, so it's a straight pass through. What I mean is this already works:

mpatches.Ellipse(ec, width=ew, height=eh, edgecolor=html_color, facecolor=mcolors.to_rgba(html_color, .10))

ETA: While I suggested an API change, maybe an alternative way to address this is another gallery example in the color section that shows how to use to_rgba to set different alpha values for different parts of a patch and line and marker and the like? Granted, I think we also should also add this sort of gallery example if (color name, alpha) becomes a supported spec too.

You can also only document to_rgba, which is less work.

it is documented: https://matplotlib.org/devdocs/api/_as_gen/matplotlib.colors.to_rgba.html but all the examples could just as easily be written using to_rgb and so it's not obvious.

Here is an implemetation for ('color', alpha) if we want to go that route.

Alternatively, I like the idea of adding an alpha example to the color gallery. I noticed the colors tutorial has a clear alpha example, although it doesn't use to_rgba().

@j1642 sorry for dropping the ball on this, I think it's still an open question on whether we want to add this additional color specification (I'm 👍) but if you're interested please open a separate PR to add an example to the docs.

ETA 2: if there's consensus, then also please add this spec to the table in https://matplotlib.org/devdocs/tutorials/colors/colors.html#sphx-glr-tutorials-colors-colors-py

I'm also inclined to add this specification.

While this is strictly redundant (color=(some_color, .5) is identical to color=mcolors.to_rgba(som_color, .5)), I think this is a usability topic. Not having to import and type mcolors.to_rgba is a sizable simplification. I also think the tuple notation is still readable enough despite being quite terse.

As opposed to my previous comment

Should we allow this for the cases tuple and hex-string as well, which already have built-in alpha support? I'm inclined to not do this, which saves us extra checks and disambiguation.

I'm quite firm now that we should allow this and not do any artificial limitations. First, the strict equivalence color=(some_color, .5) is identical to color=mcolors.to_rgba(som_color, .5) is preferable because of the simple logic. Second, there's a valid use case that one wants to add transparency to a color handed down from somewehere else. Making this work only for a subset of types is not reasonable.

Sorry haven't merged cause haven't had the time to investigate if the ci failure is related.

Appveyor failure is unrelated, unfortunately was caught by #25209 so a conflict in the tutorial has arisen

Thanks for all your patience w/ this(us) @j1642!

No problem. Thanks everyone!

I just landed on the new example Ways to set a color's alpha value (which is really well indexed by search engines!). This new syntax seems pretty handy!

Now here is my problem: I didn't know this was a new example/feature until I realized in didn't work on my setup. I don't know what is the policy for marking new features in examples, but perhaps the "version added" should be explicit in examples?

Good point! We have from 3.7 tried to make it clear in the API documentation when things was added, but here it could clearly make sense to add a note in https://matplotlib.org/devdocs//users/explain/colors/colors.html#sphx-glr-users-explain-colors-colors-py that the last format is only available since 3.8. For individual examples, I am a bit more ambiguous (although I wouldn't block a PR with that). Not sure one can expect all to include it in a sensible way and at some stage one may want to expire that information in examples.

It is a bit annoying though that the search engines are pointing to the the development docs. We used to have the opposite problem, that the hits were from 2.x...

Good point! We have from 3.7 tried to make it clear in the API documentation when things was added, but here it could clearly make sense to add a note in https://matplotlib.org/devdocs//users/explain/colors/colors.html#sphx-glr-users-explain-colors-colors-py that the last format is only available since 3.8. For individual examples, I am a bit more ambiguous (although I wouldn't block a PR with that). Not sure one can expect all to include it in a sensible way and at some stage one may want to expire that information in examples.

Interesting: I thought the other way round: put the version added to examples, because there is ample space to do that, while avoiding the clutter in the doc for color specification. In the end, there is still the fact that docs have a global version number.

And I agree along with a "version added policy" should come a sensible expiration policy (I thinking here of some Scipy function I saw the other day which was quite cluttered by old "version added" marks)

It is a bit annoying though that the search engines are pointing to the the development docs. We used to have the opposite problem, that the hits were from 2.x...

I probably landed from Qwant, so it's probably not a massive issue.

because there is ample space to do that, while avoiding the clutter in the doc for color specification.

Fair point. On the other hand the color specification is sort of "the official color specification API doc", so should be there, although it doesn't render that nicely.

I think my main "objection" is that I cannot really figure out a good way to get it into the example...

"""
In some cases, the (matplotlib_color, alpha) color format, introduced in 3.8, provides an easy way to fine-tune the appearance of a Figure.
"""
?

Or a

.. versionadded:: 3.8 
   The (matplotlib_color, alpha) color format.

at the start of the example?

We used to have a banner on devdocs; this was lost with the change to pydata-sphinx-theme. They do have an announcement banner now, though it may not work exactly the same. I am investigating if we can restore that functionality.

I think my main "objection" is that I cannot really figure out a good way to get it into the example...

plan with the tags/gsod work is to start adding a tag for when a feature was added, possibly automagically

Also, we might want to add /devdocs/ to the exclusion list in robots.txt, which would request that search engines not include links to the devdocs.