I think a border would significantly reduce the color impression. Recognizing the difference between a light color and white is harder if there is a separating line in between. The positions of the color blocks is quite clear from the layout, so a border is also not needed to indicate the position.

Some of the light colors are inherently hard to distinguish from white. We cannot do much about that.

I agree no borders is likely better.

Can I work on this ?

From the thumbs, I think we'd rather not introduce borders.

@story645 closing based on the thumbs vote. Feel free to reopen if you think we should revisit this.

@joybhallaa sorry for the red herring, for now this is not actionable.

Backgrounds always mess with perception, including the choice of a white background. For example this optical illusion where the gray swatch is all the same color:

I think the benefit of a slight very light (like two points darker than white or than the color swatch itself) edges benefit on readability/distinguishing colors outweighs color skewing effects that are already inherently in place because of having a background.

In case there is another opinion needed here, I did actually think about adding a border when updating this example in #12209 and I decided against. The reason is precisely that color perception is dependent on the color of border and background; however, since matplotlib by default has a white background, showing those colors directly on top of the white background should give the perceptually closest result to how they would look when used in a default figure.

Arguably you sometimes have a different background or other requirements, so adding a commented-out line (or an argument to the function) in the example allowing anyone running it to easily change the background color would make sense to me.

Or, if adding more complexity is not an issue, one could make it such that right clicking any color swatch would change the background of the figure to that clicked color.

The gradient background example is a bit on the extreme end 😉. In the end, every context will influence the perception of the color, whether it's background color, pattern, border, shape or size. We only need to decide which influence we want; and here I follow @ImportanceOfBeingErnest with the argument that we usually draw on white.

Nevertheless, I gave it a chance and copied the code to see how borders would look like. But turns out, adding borders is not trivial, because the color swatches are thick lines, not rectangles. One would have to rewrite the whole example to add borders. At least for me, that's too much effort given that I think it's not looking better.

I wouldn't bother with any interactivity in the example. Not because of code complexity, but because I assume that most people will only look at the rendered html version anyway. Also we shouldn't overdo it. This is "just" (sorry for the word, I know you've scolded me for that before) a reference card of the color names with some basic visualization.

All that said, I'm just one voice. As usual if there's a majority for adding a border, I won't stop that.

One would have to rewrite the whole example to add borders.

I think the example should be patches rather than hspan anyway since they are patches. I'm not terribly concerned about the amount of effort given this is an issue aimed at new contributors and I don't think learning the patch API to do it is a huge ask.

"just" (sorry for the word, I know you've scolded me for that before)

Eh, I don't think that word belongs in docs (usually), but like it's fine to use it in language. And sorry that I came off scoldy.

I think the example should be patches rather than hspan anyway since they are patches.

Agreed. Rewriting to using Rectangles would be good anyway. @joybhallaa would you be interested in picking that up?

We can later compare if Rectangles look better with or without border.

And sorry that I came off scoldy.

No, no, you were not. I just 🙄 get more conscious about my language. 😄

Hiya - there didn't seem to be any further developments on this, so I thought I'd pick it up. The commit referenced above applies the basic change to convert to use Rectangle, assuming the same widths as before. As @timhoffm suggested, this makes it much easier to test the black borders - assuming edgecolor='k', linewidth=1 we get:

I'd be happy to submit a PR as it stands (without the border) if that's suitable, or add further tweaks if needs be.

Thanks!

Awesome @asongtoruin! A PR would be much appreciated, and if it's not too much work would you mind also trying a very light gray background?

@story645 as in, a grey background to the whole page? With/without the black borders?

Sorry, meant light gray borders!

Looking at the above light borders might not be too bad after all 😄. I'm looking forward to see a picture of there.

Splitting the difference - with edgecolor='0.5':

@timhoffm are you in support of the light grey borders then? I'll put in a PR if so

My vote would be to stick to a borderless visual per my comment above.

Agree w @ImportanceOfBeingErnest colours should be shown in the context they are most likely to be used and for us that is against a white background.

Then I think it should be with a black border since axis are black 90% of the time and they provide a visual border. Can the PR be put in & then we decide on there being a border?

I think coloured lines are typically drawn on a white canvas.

I think the pale colors are more often used as backgrounds or fills, or at least that's how I use 'em. But I also think that the impact of the border on the perception of the color is a lot smaller than the clarity gained by having it.

Perception depends a lot on background and on the size of the colored area. If we care about that, we'd need at least:

• blocks without border on white background (as we have currently) - repesenting filled Artists, which by default have no border.
• thin lines on white background - representing Line2D.

But I wouldn't care to go down that road. This is just" an illustration for the color names, so I'd keep it simple with one representation of the colors.

Coming back to the basics, we would like to have this rewritten using patches instead of hspan. (#15614 (comment)). This can ce done indepentently on whether we add a border later or not.

@timhoffm PR above for the basic rewrite.

Personally, I find the colours easier to perceive with the border, but I can see the idea behind keeping the comparison directly against white.

fwiw I personally like the thin outlines; it is true that our colors are typically used without outlines but they're also most often points or lines, nor rectangles, so heh.