Design Doc

[nathany]

We should write down our goals, features, the the API design. We could do it here in an issue, but a Google Doc might work better.

• [x] create a Shields badge specification
• [ ] goals
• [ ] features
• [ ] specify a recommended Shields API design

[olivierlacan]

I'd rather have this be written down in Markdown and versioned here. Google Docs is atrocious at versioning.

Much of this was in the original README, not sure why @whit537 wiped it when he setup GitHub Pages. I'm going to partially revert that.

I'm going to double down on clarifying the Shields specification in the README because there's a lot of redundant conversations about things we already solved last year with @ackerdev going on in Issues.

[chadwhitacre]

Sorry, I moved it to the gh-pages branch. You're right that we need something more on master, since that's the default branch.

[olivierlacan]

@whit537 It's cool. :smiley_cat: https://github.com/badges/shields/blob/master/README.md

[chadwhitacre]

:-)

[olivierlacan]

I added tasks to @nathany's original post and a first draft of the specification is ready:

• Specification

We definitely a Goals section that improves upon this:

A legible & concise status badge solution for third-party codebase services.

[chadwhitacre]

@olivierlacan On the call w/ @espadrine today, we discussed the idea of making SVG the primary badge, with PNG etc. as secondary byproducts. The major implication of that upon the design is that using Open Sans makes SVG badges much larger in file size than using, e.g., Verdana, because we have to embed Open Sans. We may be able to mitigate that somewhat by subsetting; it's unclear at this point by how much. I see that you're -1 on "Verdana (a sloppy Futura ripoff)." Do you agree with the shift to SVG as primary? How would you like to see the font file size issue addressed?

[olivierlacan]

@whit537 With this many known issues unresolved:

It's hard to agree with using SVG as the primary. This is basically the same conclusion we reached sometime last year. SVG is a great ideal solution, but in practice it has many show-stopping flaws.

I vaguely remember @ackerdev last year trying out subsetting and not seeing a significant reduction in file size on the SVG with embedded fonts.

Having an API that can easily output PNGs is the road we started on because of this imperfect reality. As soon as SVG is widely and reliably supported then I don't see why we would wait a second to jump on it though.

Essentially I think we should give users a choice:

• use this universally supported 2x PNG in an HTML image tag and it will look great everywhere
• use this experimental SVG that is almost supported properly everywhere

Now let's compare at 200%

• I think b.adge.me padding is wrong, minor issue
• b.adge.me is missing a drop shadow to increase legibility on the right side text (value)
• the b.adge.me font is bolder, probably due to a font rendering setting or to the font itself, despite the larger strokes it's often harder to make out individual glyphs. Look at the lowercase "i" and the lowercase "l" in the screenshot below:

At 100%:

It's also nearly impossible to distinguish between the "i" and the "l" in the world "failing". This is why I think typeface choices matter a lot, especially with dynamic text.

@whit537 What font-size issue are you talking about? The one I just mentioned?

[espadrine]

@olivierlacan That's a comparison on your system, right? We should compare across the board, {Windows, Mac, Retina Mac, Linux, Retina Linux} x {IE, Firefox, Chrome, Safari}.

How would you go about supporting all of these in PNG in Markdown? From what I understand, the 2x PNG has a separate URL.

Also, how do we support 3x?

[espadrine]

About text shadows: they look ok on my screen, but I was advised against for legibility reasons.

Here's b.adge.me with text-shadow: .

[ackerdev]

@olivierlacan I never got a chance to try embedding an SVG font, because right after we were starting to talk about doing something like that, we had run into the problems with delivering an SVG, so I stopped looking into it to start looking into PNG output. I had been talking about it in https://github.com/badges/shields/issues/11#issuecomment-13265118 though. IIRC Firefox doesn't like external fonts being referenced in the SVG, so embedding a subset of the font might be your only real option.

@espadrine The comment you linked to didn't say to remove the text shadows, they were commenting that they made the text look too 3d (because @2x rendering of it, the shadow spilled out on the left and right sides of the text making it look like blocks). The text-shadow is extremely important for legibility, they help with contrasting the white text against the colored background.

[nathany]

I'm more than happy to use Markdown. How about we do separate docs for the visual design of the badge and the API design? (One will inform the other)

Let's have separate people leading up each.

[espadrine]

@ackerdev Doesn't text shadow and "3D-like" look go hand in hand?

FWIW, the person that wrote the comment I linked to (which happens to be working at Travis-CI!) favors the shadowless design currently in use.

[chadwhitacre]

What font-size issue are you talking about? The one I just mentioned?

Sorry, meant "file size" (edited above).

[ackerdev]

@espadrine If you want to get literal over it, yes. I was just using wording similar the comment you linked to in that thread, where @henrikhodne was commenting on the drop-shadows spilling over to the sides, which looks a bit sloppy and I presume he was saying it felt disconnected from the badge itself. I'm not entirely convinced that your other link to his comment signifies anything about him preferring it shadowless, either, rather that the shadowless one didn't have the problem of having a shadow that could spill out and look weird. I'd be happy to hear him clarify, but without it I don't believe that's what he really meant by that.

Not as a comment on your design, but I think the shadowless version is terrible. Feels like the text was an afterthought to the design and lowers legibility on colors that don't contrast enough on white, like green and yellow.

[sarahhodne]

To clarify: I'm ok with drop shadows, it's just that the "shadows" I was seeing (mostly the white shadow, IIRC) looked a bit odd.

[espadrine]

What kind of drop shadow would work then? @ackerdev, does your comment on the legibility of drop-shadow applies to the shadowful b.adge.me image I provided? Is that more legible than the b.adge.me we have now?

(Note: it's a really easy change. I'm genuinely looking for feedback, as it looks just as legible to me.)

[ackerdev]

Yes, I believe that with drop shadow, the badge's legibility is significantly better. There are a few other issues I see with it's legibility related to how that font performs at that size (like the i's looking a lot like l's), so I wouldn't say it's perfect, but I would say the drop shadow version is definitely better.

[tabatkins]

Agree, shadowed one is substantially better.

[chadwhitacre]

With this many known issues unresolved: [image] It's hard to agree with using SVG as the primary.

Per https://github.com/badges/shields/issues/94#issuecomment-31823538, my understanding is that these issues have already been addressed in gh-badges (yes, @espadrine?). They are not a reason not to make SVG primary.

[espadrine]

Per #94 (comment), my understanding is that these issues have already been addressed in gh-badges

Yes.

Besides, I noticed that patches in both Firefox and Blink are on their way, which gives us a free(-er) hand in case we want to re-design the badges.

[espadrine]

Something relevant to this thread: what colors should we use for various vendors?

Currently in b.adge.me, I use "brightgreen" to indicate the best situation for some badge vendors, and "green" for others.