tools/work/README.md fixup

[achadwick]

1. I fixed a few Markdown issues that were breaking some of my editors that have weaker Markdown processors.

   • Indented fenced code blocks are not widely supported, comments especially
   • The doc is still dependent on indented fences toward the end, but it degrades cleaner for single lines ;)

2. Added a list of exceptions where pure #fff and #000 are allowed.

3. Updated the Debian commands for newer releases.

   • Scour is now python3-scour

4. Removed dangerous instruction to use sudo pip install scour

   • Mostly unnecessary, because Debian is now up to date, so don't give an example any more and demote the info
   • It was always dangerous to go messing with the Python libs tree like this
   • Debian has moved to externally-managed-environment, so pip works in fewer cases anyway
   • The modern advice is to use pipx on Debian 12 or later, particularly for comamnd line utils like scour

[achadwick]

I'm still confused about what the docs mean by "compabillity with mostly GTK Themes", btw.

[morganist]

this compatibility talks about the choise of standard black and white colours, an it appears that the present combinations were tested with different gtk colour themes. that's the reason why we even define them as standard and discourage the use of plain white and black colours.

[morganist]

hey, great rewrite, I always wanted to at least improve the grammar and the wording, but never got to it. thanks! however, could you please change the section about exceptions that concerns the use of pure white? I believe it should be "it is appropriate to also use pure white" in logos/text/other designs on top of colored icons, instead of an imperative. The base colours of Papirus can make pure white stand out too much if it is used in every situation, and almost all our present fullcolour icons use white elements in #e4e4e4

[morganist]

it just that i generally believe #e4e4e4 should be used everywhere, and pure white should be used only if it looks really wrong.

[achadwick]

@morganist
Agreed. I'll make it clearer that I'm not talking about the base shapes. Better to say that pure '#ffffff' or '#000000' is never appropriate for those base elements (apart from their highlights and shadows, with transparency). For logos or symbols atop the base, pure white or sometimes pure black can also be appropriate

(Aside: mediaeval heraldry would call the logos and symbols charges and the base shapes fields, so this is kinda like reinventing the rule of tincture, I guess… well, not that pure black is a "metal". It might be a bit more modern to point at WCAG2.0 AA or AAA contrast ratio standards somewhere, though 😅)

So, a plan for me in this update:

• Make the distinction between symbol and base clearer in the docs
  • and say that pure ff or 00 are never appropriate for bases
  • fine for symbols on top of those base colours though
• Make it clear that the "outline" handwave used elsewhere applies to both levels, or perhaps just say "clear shapes"
• Suggest choices that favour contrast and clarity of foreground to background
  • there are a few icons which have subpar choices for symbol:base (foreground:background) contrast already, so I think the docs could benefit from this update
  • it matters for accessibility especially. We could suggest a WCAG 2.0 level in a future edit. AAA would be very achievable, and AA would be better still, but tends to mute foreground elements on whiteish backgrounds
• Stress that Papirus's non-symbolic icons have to display well on both light and dark themes, potentially with pure white or black backgrounds themselves
  • increasingly so, actually, given direction of a lot of theme design these days

(Another aside: I'm actually more in favour of the Papirus "coloured base" style over the e4 grey or any other light grey or white as a paper colour. Why? I'm an obligate light theme user, and really often the tab of the common "document" background disappears in themes whose background aren't too glaring white, simply because the tabs are that bit lighter than the e4 base shade: fa vs the theme's f7.

I don't want to rock the bot too much right now and start suggesting that nobody uses
#e4e4e4 grey bases for new icons though 😉 )

[achadwick]

it just that i generally believe #e4e4e4 should be used everywhere, and pure white should be used only if it looks really wrong.

Is that just for bases, or for the designs on top? If it's just for bases, I agree 100%. The designs though very often benefit from the added contrast of using pure white and black, and for these overlaid designs it's actually established Papirus practice for the common design of a logo over a coloured rather than a monochrome background. Check out the mimetypes folder with an eye dropper tool ;)

[morganist]

it's actually established Papirus practice for the common design of a logo over a coloured rather than a monochrome background. Check out the mimetypes folder with an eye dropper tool ;)

mimetypes icons are a bit different, i think. i mainly fiddle with application icons, and they are often a variation of a basic coloured shape and a logo in #e4e4e4 examples include telegram icon, signal icon, obs icon, librewolf icon, etc. all is good, i just think it's really not necessary facilitating the use of pure white through documentation. current white gives this, i don't know, paper-y feel to Papirus icons, even is the element is inside the base shape.

The designs though _very often_ benefit from the added contrast of using pure white and black

yeah, exactly. this is one of the cases where it is absolutely appropriate to use pure white/black – in combination with #e4e4e4 and/or #4f4f4f . but not if it would be the only white/black, that's inconsistency and we shouldn't want that. that is, unless we revisit the contrast, as you've proposed ;)

[morganist]

in #3921 for example, the logo is clearly too white for a Papirus icon, and the contrast with the backgroung is sufficient to use #e4e4e4

[achadwick]

Is ff white too much?

in #3921 for example, the logo is clearly too white for a Papirus icon,

I kinda disagree here even for a largish foreground element like the shield. I think the e4 grey looks very dull indeed on a light background, and ff is just better to me, against the current Adwaita's extremely bright #ff active and f7 inactive backgrounds, and also against the ff light mode here on Github. Adwaita is the current GNOME theme.

Comparing e4 , ff , and e4 as a potential compromise, only the ff and e4 look any good to me against modern Adwaita.

Contrast

and the contrast with the backgroung is sufficient to use #e4e4e4

All the e4/f4/f4 shades above are fine against the #AA3FE4 example background at https://webaim.org/resources/contrastchecker/ for graphical elements. However, only #FFFFFF is any good for ordinary size text (you never really get visually large text inside an icon unless it's a single letter!).

Arguably, there is a difference between sharp lines and big blocks for foreground elements. There, perhaps a good compromise would be to suggest an intermediate colour, like #e4e4e4.

Of course, that's just one example, and we don't yet tell contributors to check WCAG 2.0 contrast ration.

[achadwick]

Existing examples

There really are lots of examples in Papirus where pure white is used, even for very large elements, and the result is juicy and fresh and Papirus-ish. I think these are perfectly correct, and would look so much worse if e4 grey was used instead:

• in mimetypes:

• in apps:

Observations: I love that clementine icon so much. Mimetypes really are not special, I think. But notice how the examples have their ff element surrounded by darker colours or shades! That's what I'm trying to get across. The character icon eyes (in apps) would look especially weird if they were redone as e4. This is what I mean by a "foreground element" or "logo" element of the icon, and I think we need to make that distinction.

There are as many places where ff white really should not be used for a "white" element, and is rightly avoided. Not really counterexample here: they're all examples where there are white or off-white objects that would sit directly on a potentially white background, and they should follow a different rule. I am not proposing to change the e4 ruling for these elements at all. This is what I mean by the "base" element of the icon.

• in mimetypes:

• in apps:

[achadwick]

In other words, I think the existing suggestion to use e4 grey and nothing brighter for white objects has arisen only from considering what I'm describing as a base element. It makes a lot less sense to apply it to foreground elements, and designers of established icons have ignored the e4 suggestion in apps and also in mimetypes for elements on top of the base, or surrounded by contrasting colours.

Anyway, I'll try and summarise all of that into this PR, and we'll see if that's acceptable.

[wilwarindi]

@morganist @achadwick So do I change the white in #3921 or not? I'm OK either way. I would prefer something in between pure white and the grey, but also consistency is important.

[achadwick]

So do I change the white in #3921 or not? I'm OK either way. I would prefer something in between pure white and the grey, but also consistency is important.

@wilwarindi
I'd wait a little while, and leave it as it is till this is decided. @morganist has the commit rights, not me.

I don't think there's currently a fixed palette, and that's one of the changes I want to make in this README. I think it's better to think of the README's "black" and "white" as high and low brightness limits for base elements colours instead. They're like that to look as good as possible against different themes. Foreground elements are isolated from the theme background colour by the base elements, so they can go brighter or darker, as appropriate.

I'm a fan of that f4 light grey for an intermediate foreground colour, if e4 looks dull there and ff is too glaring. What do you think? I could suggest it in the doco revision.

[achadwick]

I honestly think that ff white is perfectly appropriate in most situations where the base colour isn't too bright itself. the examples in #3912 (comment) really do look good to me still.

[wilwarindi]

My modest proposal would be this:

It's at what Inkscape calls 7,5% grey, or #ecececff.
The #E4E4E4 is basically the same as 10% grey.

[achadwick]

OK, I hope this new draft makes everyone happy. I've really tried to clarify why those two black and white colours are stipulated. Better to think of them as brightness limits that make base shapes stand out against commonly available GTK themes.

Surprising Papirus fact: pure black really is only used for shadows. Its usage is totally different from pure white, which is a lot more widely used - but only really for foreground designs.

👉 https://github.com/achadwick/papirus-icon-theme/blob/toolswork-readme-fixup/tools/work/README.md

It's getting a bit big now, and I could split it.

[morganist]

@achadwick you opened my eyes to the fact that brighter white is really widely used, as it turns out. I never really noticed any clash between similar icons with different shades of white on the foreground when they are placed on a dock or a panel, so I guess you are totally correct about the use of white colours.
I reviewed your improved readme and I'll say it's ready to merge!

[achadwick]

I think that's it, ready for proofreading! A few late changes just now:

• I split out the design notes into a separate document to get it away from all the notes about the scripted workflows.
• Added a note to DESIGN.md about how to avoid using gradients.
• Various typos and grammatical fixes.
• I've updated the main README to point at the new docs, to aid onboarding.

Over to you, @morganist :D

[morganist]

that's an awesome change to our documentation, thank you very much!