Write some documentation about use of colours

[chris48s]

📋 Description

We've had a couple of PRs recently where contributors have wanted to contribute badges using branded colours in preference to the standard palette.

We have some pretty good docs we can point to when it comes to thing like conventions for badge URLs but I'd like to have some guidance written down about use of colours.

I need to have a think about exactly what to write, but the key point is basically: We use colour to convey information and ensure consistency, not to promote a project or brand. There may also be a few places where we need to pull some older services into line with this as part of writing the guidance.

This is related to shields values of being semantic and non-promotional

[chris48s]

OK. So I've had a bit of a think about this.

First off, I think there are several services where we're violating this principle that colour should be semantic and not promotional. These are:

• Docker
• Thunderstore
• Cocoapods
• Pulsar
• Vaadin Directory
• Gerrit

and as part of this we should get our house in shape and fix them.

I think the key points I want to hit in the docs are:

• Colour should be used semantically. We use colours to communicate information about the message displayed on the badge, not to promote a project or brand.
• If your badge fits into a standard category (e.g: build status, version, number of downloads, coverage %), use an existing helper function (which already encode some decisions about colour scheme)
• Use named colours rather than hex values
• Label should always use the default #555555

Then I think there are some kind of base guidelines to start from. Maybe:

• Nominal value: blue
• Ordinal continuous value (bigger number is "better" or smaller number is "better"): use floorCount()
• Ordinal discrete value: use a colorScale()

I also think we probably want to frame this second section as a set of starting assumptions rather than hard rules. I'm sure there are places where we've deviated from that for good reasons, but I think there is value in documenting "given no other information, start here".

[jNullj]

We already refer to it in the spec:

shields/spec/SPECIFICATION.md

Line 9 in d4090a2

- **non-promotional**: badges should refrain from advertising a service but instead provide value through the badge's information instead

I noticed we have an exception for social badges like X (twitter), GitHub stars etc...
We might want to refer to these as well or take a decision about them.

We could change the developer-experience by making the use of helper functions mandatory by default so using a unique render starts a discussion. On the other hand this is a bit extreme and will result in many exceptions in code.