[Worg] Proposing a few CSS changes

[Worg] Proposing a few CSS changes

[Adam Porter]

[-- Attachment #1: Type: text/plain, Size: 135 bytes --]

Hi,

I'd like to propose some changes to Worg's CSS that I think make it much
more readable.  Here are some before/after screenshots:


[-- Attachment #2: Before changes, in full-width browser window --]
[-- Type: image/png, Size: 234282 bytes --]

[-- Attachment #3: Before changes, in half-width browser window --]
[-- Type: image/png, Size: 221125 bytes --]

[-- Attachment #4: After changes, in full-width browser window --]
[-- Type: image/png, Size: 322462 bytes --]

[-- Attachment #5: After changes, in half-width browser window --]
[-- Type: image/png, Size: 328754 bytes --]

[-- Attachment #6: Type: text/plain, Size: 1380 bytes --]


The changes are simply removing some rules, which allows the user's
configured browser font settings to be applied, as well as setting the
max-width of the content to 60em.  In CSS terms, Firefox's inspector
provides this copy of the changes:

#+BEGIN_SRC css
  /* worg.css | https://orgmode.org/worg/style/worg.css */

  @media all {
      body .title {
          /* font-size: 22pt; */
      }
      h1 {
          /* font-size: 2.1em; */
          /* margin-top: 10px; */
          /* margin-bottom: 10px; */
          /* margin-right: 7%; */
          /* color: grey; */
      }
      body {
          /* font-size: 14pt; */
          /* line-height: 22pt; */
      }
      html {
          /* font: .9em/1.6em "Droid Serif", Cambria, Georgia, "DejaVu Serif", serif; */
      }
      h2 {
          /* font-family: sans-serif; */
          /* font-size: 1.45em; */
          /* padding: 10px 0 10px 0; */
          /* color: black; */
          /* padding-top: 1.5em; */
      }
      h3 {
          /* font-family: sans-serif; */
          /* font-size: 1.3em; */
          /* color: grey; */
          /* margin-left: 0.6em; */
          /* padding-top: 1.5em; */
      }
      body #content {
          /* max-width: 70%; */
          max-width: 60em;
      }
  }
#+END_SRC

If these are agreeable, I can apply them to the Worg repo.  Please let
me know.

--
Thanks,
Adam

Re: [Worg] Proposing a few CSS changes

[Eric S Fraga]

On Thursday, 23 Sep 2021 at 21:37, Adam Porter wrote:
> The changes are simply removing some rules, which allows the user's
> configured browser font settings to be applied, as well as setting the
> max-width of the content to 60em.  

I fully support this.  Specifying font sizes is never a good idea.

-- 
: Eric S Fraga via Emacs 28.0.50, Org 9.5-dev-g4271f2
: Latest paper written in org: https://arxiv.org/abs/2106.05096

Re: [Worg] Proposing a few CSS changes

[Bastien]

Hi Adam,

Adam Porter <adam@alphapapa.net> writes:

> If these are agreeable, I can apply them to the Worg repo.

Sure, please go ahead!  Thanks,

-- 
 Bastien

Re: [Worg] Proposing a few CSS changes

[Adam Porter]

Bastien <bzg@gnu.org> writes:

> Hi Adam,
>
> Adam Porter <adam@alphapapa.net> writes:
>
>> If these are agreeable, I can apply them to the Worg repo.
>
> Sure, please go ahead!  Thanks,

Hi Bastien,

Thanks.  Since Timothy has some thoughts on these changes, I'll wait
until we come to a consensus on them.  :)

Re: [Worg] Proposing a few CSS changes

[Timothy]

[-- Attachment #1: Type: text/plain, Size: 1908 bytes --]

Hi  Adam,

> I’d like to propose some changes to Worg’s CSS that I think make it much
> more readable.  Here are some before/after screenshots:

Thanks for proposing these changes to Worg’s CSS. I have a few thoughts on them,
which I will share below.

> The changes are simply removing some rules, which allows the user’s
> configured browser font settings to be applied, as well as setting the
> max-width of the content to 60em.  In CSS terms, Firefox’s inspector
> provides this copy of the changes:

I’m a big fan of the shift to a fixed em-based max width. However, I’m not quite
sold on a few of the other changes, for instance the font change. While it does
vary, I must say than in particular I find the default serifed font of browsers
somewhat unattractive. Have you considered instead a sans-serif system font
stack? For example, this is what I used on the homepage:
┌────
│ -apple-system, BlinkMacSystemFont, San Francisco, Helvetica Neue, Helvetica, Ubuntu, Roboto, Noto, Segoe UI, Arial, sans-serif;
└────

Regarding the header colour, while I’m not much of a fan of the original grey,
perhaps this would be a chance to introduce some visual ties with the rest of
the site and the logo, for example by setting the heading colour to `#587e72' (the
dark gree from the Org logo).

I also tend to find the default font size slightly to small on most browsers.
I’d be in favour of bumping up the base fontsize to `1.2rem' and changing the
width restriction from `60em' to `60rem' so it remains constant.

Lastly, on padding, I feel you may have been a bit over-zealous in your removal
of padding from headlines. IMO a bit more space helps visually separate sections
and let them “breath”, and browsers defaults tend to pack things a bit more
densely than I would.

That’s it from me 🙂.

All the best,
Timothy

Re: [Worg] Proposing a few CSS changes

[Adam Porter]

Hi Timothy,

Timothy <tecosaur@gmail.com> writes:

> I’m a big fan of the shift to a fixed em-based max width. However, I’m not quite
> sold on a few of the other changes, for instance the font change. While it does
> vary, I must say than in particular I find the default serifed font of browsers
> somewhat unattractive. Have you considered instead a sans-serif system font
> stack? For example, this is what I used on the homepage:
> ┌────
> │ -apple-system, BlinkMacSystemFont, San Francisco, Helvetica Neue, Helvetica, Ubuntu, Roboto, Noto, Segoe UI, Arial, sans-serif;
> └────

I think the default serif font varies by platform, e.g. MacOS browsers
will use a much different one than Windows ones.  As well,
platform-based differences in font rendering (especially between MacOS,
Windows, and GNU/Linux) have a significant effect on the end result.

IMHO, I prefer not to "chase" issues like this by trying to account for
them in CSS.  This is why I prefer to remove font specifications for
documentation pages: let the user decide.  I find it frustrating when
I've configured my browser to use a readable font for long documents,
but the site "commandeers" the font to something that may only look nice
and readable on the author's system.

As for serif vs sans-serif, I think serif fonts are much easier to read,
and AFAIK "research" backs this up.  :)  That's not the only
consideration, of course, and I wouldn't suggest changing the main Org
site to use a serif font.  But for wiki/documentation sites, I think
serifs are a better choice.

But if we remove the font specification altogether, users who prefer
sans-serif fonts and use that setting in their browsers will see
sans-serif.  I think that, for long texts and documentation, it's
important to let the user control the appearance of main body text as
much as possible.

> Regarding the header colour, while I’m not much of a fan of the original grey,
> perhaps this would be a chance to introduce some visual ties with the rest of
> the site and the logo, for example by setting the heading colour to `#587e72' (the
> dark gree from the Org logo).

I think that'd be nice, yes.

> I also tend to find the default font size slightly to small on most browsers.
> I’d be in favour of bumping up the base fontsize to `1.2rem' and changing the
> width restriction from `60em' to `60rem' so it remains constant.

I'll push back on this change strongly.  :)  I really hate it when sites
increase the default font size for body text.  I've configured my
browsers to use the font size that's most readable and useful for me.
There seems to be an "epidemic" of sites increasing the default font
size nowadays; sometimes only one or two paragraphs are visible on a
single screen of text.  Again, I think this is an attribute we should
leave entirely to the users to configure.

> Lastly, on padding, I feel you may have been a bit over-zealous in your removal
> of padding from headlines. IMO a bit more space helps visually separate sections
> and let them “breath”, and browsers defaults tend to pack things a bit more
> densely than I would.

I could live with adding a little bit of padding back, but not too
much.  There's already way too much whitespace on the Web.  ;)

If you like, I'll prepare a new "patch" and post screenshots so we can
try to reach consensus.

-- 
Thanks,
Adam

Re: [Worg] Proposing a few CSS changes

[Timothy]

[-- Attachment #1: Type: text/plain, Size: 891 bytes --]

Hi  Adam,

A quick note following on from your comments.

> I find it frustrating when I’ve configured my browser to […]

I think this is the source of our differences of opinion. I personally haven’t
touched my browser’s default CSS, and am not a fan of the default styling, but
clearly you have changed your browser’s default CSS to something that you find
works well.

This leads me to a slightly conflicted position, because I both like the idea
that if the user has set up their browser to use a font they like, a text size
they like etc. that sites would respect that. But I also suspect that very few
people ever do this, and am not that happy about how things look with unmodified
browser defaults. Here I lean towards trying to ensure the best average
experience, and unfortunately I think that means overriding the default CSS.

All the best,
Timothy

Re: [Worg] Proposing a few CSS changes

[Adam Porter]

Hi Timothy,

Timothy <tecosaur@gmail.com> writes:

>> I find it frustrating when I’ve configured my browser to […]
>
> I think this is the source of our differences of opinion. I personally haven’t
> touched my browser’s default CSS, and am not a fan of the default styling, but
> clearly you have changed your browser’s default CSS to something that you find
> works well.
>
> This leads me to a slightly conflicted position, because I both like the idea
> that if the user has set up their browser to use a font they like, a text size
> they like etc. that sites would respect that. But I also suspect that very few
> people ever do this, and am not that happy about how things look with unmodified
> browser defaults. Here I lean towards trying to ensure the best average
> experience, and unfortunately I think that means overriding the default CSS.

No, I haven't changed my browser's default CSS, only the font settings
in preferences.  These are standard features, having been present on
browsers for decades, are easily adjusted by any user, and ideally they
should take into account platform defaults as well.  These include both
font family and size.

We should keep in mind that the platforms and systems which view the
site are wide and varied.  Some users may have high-DPI monitors in dim
environments, others may have low-DPI monitors in bright environments;
some users may have perfect eyesight, while others may be legally blind.
Some users may use an OS that uses strong hinting (e.g. MS-Windows),
while others may use one that does little-to-none (e.g. MacOS).  Because
of those factors, there is no good default for us to use; what looks
good on our systems may look very poor or even unreadable to other
users.

So I think it's very important to respect the user's settings,
especially for long texts and documentation (i.e. not the "home page"
parts of Web sites whose purpose is to present projects as a whole).

Re: [Worg] Proposing a few CSS changes

[Stefan Nobis]

Adam Porter <adam@alphapapa.net> writes:

> So I think it's very important to respect the user's settings,
> especially for long texts and documentation (i.e. not the "home page"
> parts of Web sites whose purpose is to present projects as a whole).

+1.

HTML pages are neither books nor PDFs nor advertising columns. I have
a LaTeX background and I like to tweak the micro-typography of my PDF
documents (and I find many documents out there quite ugly and hard to
read). Therefore I think I understand and kind of sympathize with
Timothoys point of view.

But the web is quite a different beast. User choices like
Window/viewport size, fonts (serif, non-serif, size,...) are way too
often ignored and even battled against. Sometimes I get the
impression, that every time a web designer gets informed about a new
way for users to override design decisions they try to block these
possibilities - and in most cases to the disadvantage of users.

Yes, today seldom people play with the font settings in their
browsers. But why? I think, because they see that these settings seem
to never really work. Even if you configure your browser to ignore
font settings from HTML/CSS and always use the browser settings, many
pages will be next to unreadable - the layout breaks down, if the
wrong fonts/sizes are used.

Therefore I support Adams wish to honor the configuration of users.
The web should be more seen as a documentation system, not an
installation of art.

-- 
Until the next mail...,
Stefan.

Re: [Worg] Proposing a few CSS changes

[Timothy]

[-- Attachment #1: Type: text/plain, Size: 1660 bytes --]

Hi  Stefan,


Stefan Nobis <stefan-ml@snobis.de> writes:

> [*snip*]
> Therefore I support Adams wish to honor the configuration of users.

Thanks for chiming in Stefan, I’m coming around to the parts of the view you and
Adam seem to share. I’m now thinking that with the font, font size, and viewport
settings, that it would make sense for Worg to just use the Browser default.

I don’t think a completely spartan page is entirely sensible though. IMO it’s
probably worth doing more to create visual links to the rest of the Org site —
I think there’s value in maintaining broad consistent stylistic choices. It
gives a sense of cohesion to the site, and as much as I’m loath to say it, helps
with “brand identity”. I think we should be able to implement some tweaks along
these lines that don’t just steamroll user preferences, where they are set.

> The web should be more seen as a documentation system, not an
> installation of art.

Style should certainly not impede the accessibility of the pages, however even a
dry technical document has stylistic choices, and I don’t think we should shy
away from that.

That’s my 2c. Anyway, back to the specific changes proposed by Adam, my current
thoughts are:

• Yes to the font, font-size, margin, and padding changes
• Still a big fan of the 60em font width. I do think 60rem may be a tad
  more sensible, but it probably makes no difference
• Change the headings to Org dark green coloured instead of default/black
• In a similar vein, maybe the link styling from <https://orgmode.org> could also
  be copied over?

All the best,
Timothy

Re: [Worg] Proposing a few CSS changes

[Stefan Nobis]

Timothy <tecosaur@gmail.com> writes:

> I don’t think a completely spartan page is entirely sensible though.

Indeed! I did not want to argue for all or nothing. :)

But font and font size for big chunks of text are quite important and
individual choices. So the rest of the styling should try to be
flexible enough to support different user choices as good as possible.

BTW: I like your design for the Org homepage. My thoughts should only
be seen as a very light weight on Adams side when trying to balancing
the scale of the multitude of styling choices. :)

-- 
Until the next mail...,
Stefan.

Re: [Worg] Proposing a few CSS changes

[Eric S Fraga]

On Saturday, 25 Sep 2021 at 19:37, Adam Porter wrote:
> This is why I prefer to remove font specifications for documentation
> pages: let the user decide.

+1 on this (and on size specifications).  Please keep the settings as
generic as possible and let me, the viewer, decide actual font and
sizes.

Thank you,
eric

-- 
: Eric S Fraga via Emacs 28.0.50, Org 9.5-g9a4a24
: Latest paper written in org: https://arxiv.org/abs/2106.05096

Re: [Worg] Proposing a few CSS changes

[Thomas S. Dye]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> On Saturday, 25 Sep 2021 at 19:37, Adam Porter wrote:
>> This is why I prefer to remove font specifications for 
>> documentation
>> pages: let the user decide.
>
> +1 on this (and on size specifications).  Please keep the 
> settings as
> generic as possible and let me, the viewer, decide actual font 
> and
> sizes.
>
> Thank you,
> eric

+1

--
Thomas S. Dye
https://tsdye.online/tsdye

Re: [Worg] Proposing a few CSS changes

[Max Nikulin]

On 26/09/2021 02:51, Timothy wrote:
> 
> I’m a big fan of the shift to a fixed em-based max width. However, I’m not quite
> sold on a few of the other changes, for instance the font change. While it does
> vary, I must say than in particular I find the default serifed font of browsers
> somewhat unattractive. Have you considered instead a sans-serif system font
> stack? For example, this is what I used on the homepage:
> ┌────
> │ -apple-system, BlinkMacSystemFont, San Francisco, Helvetica Neue, Helvetica, Ubuntu, Roboto, Noto, Segoe UI, Arial, sans-serif;
> └────

Sorry if it is a false alarm, I do not have enough experience with CSS.

Since "Noto Serif" font exist, is just "Noto" enough to select namely 
"Noto Sans"?

Concerning "em" and "rem", I may be wrong, but Chromium on Linux may 
apply font settings from desktop theme to <body> element, while "rem" 
units are based on <html> element. So using rem for max-width and 
leaving font-size to user defaults may result in too narrow or too wide 
text column. Unsure if values like "larger" are more "portable" for 
font-size of header elements.

Modern browsers support light and dark themes. I can not suggest CSS 
snippets for that since I have never played with such selectors yet.

I do not know what is the proper balance of overriding of defaults. I 
consider default built-in styles as compatibility mode with old pages. 
That is why I do not think that relying on default styles only (even 
some users customize them) is a good idea. Absolute font size may be 
left as in user preferences.

Re: [Worg] Proposing a few CSS changes

[Timothy]

[-- Attachment #1: Type: text/plain, Size: 161 bytes --]

Hi Adam,

From the last few messages in this thread, I think we’ve reached agreement on
the changes. Would you like to go ahead?

All the best,
Timothy

Re: [Worg] Proposing a few CSS changes

[Adam Porter]

[-- Attachment #1: Type: text/plain, Size: 564 bytes --]

Timothy <tecosaur@gmail.com> writes:

> From the last few messages in this thread, I think we’ve reached agreement on
> the changes. Would you like to go ahead?

Hi Timothy,

Sure, I've just pushed these commits:

dc27628 * worg.css: Adjust margin/padding for H1-H4
e6596a8 * worg.css: Change link colors
d93c8ae * worg.css: Set h2-h4 colors to the dark-green Org color
26b5cdd * worg.css: Set body#content max-width to 48em
69c60dc * worg.css: De-specify font, font-size, line-height, heading colors

Here are a couple of screenshots showing the before/after:


[-- Attachment #2: Before changes --]
[-- Type: image/png, Size: 267153 bytes --]

[-- Attachment #3: After changes --]
[-- Type: image/png, Size: 327441 bytes --]

[-- Attachment #4: Type: text/plain, Size: 916 bytes --]


Note that, after I made the other changes, the links scattered around
the page clashed very badly with the nice "Org green" and black theme,
so I adjusted them as well (as detailed in the commit message).  I tried
using "Org green" for the link text, but it seemed too low-contrast, as
well as a bit distracting while reading, so I opted to use colorize just
the underlines, and to make the link text green when hovering.

Note as well that I ended up using 48em for the content width due to the
unicorn logo in the corner being covered up by wider content than that
(in a half-1080p-width browser window, which seems like an important use
case to consider).

And I left the H1 header black rather than green, because it didn't seem
to stand out enough as the page heading when it was also green.

Hopefully these changes are acceptable, but they can always be further
adjusted if necessary.  :)


-- 
Thanks,
Adam

Re: [Worg] Proposing a few CSS changes

[Timothy]

[-- Attachment #1: Type: text/plain, Size: 1332 bytes --]

Hi Adam,

> Sure, I’ve just pushed these commits:

Great! I’ve just taken a peek and it’s a clear improvement in my eyes 🙂.

> Note that, after I made the other changes, the links scattered around
> the page clashed very badly with the nice “Org green” and black theme,
> so I adjusted them as well (as detailed in the commit message).  I tried
> using “Org green” for the link text, but it seemed too low-contrast, as
> well as a bit distracting while reading, so I opted to use colorize just
> the underlines, and to make the link text green when hovering.

I just had a look at this, and I tried a darkened green (#08402e). I think this
may be the best option.

> Note as well that I ended up using 48em for the content width due to the
> unicorn logo in the corner being covered up by wider content than that
> (in a half-1080p-width browser window, which seems like an important use
> case to consider).

We should probably update the “angry unicorn” to the logo on the homepage,
perhaps <https://orgmode.org/resources/img/org-mode-unicorn.svg> or a simplified
version.

> And I left the H1 header black rather than green, because it didn’t seem
> to stand out enough as the page heading when it was also green.

The contrast looks good to me 👍.

All the best,
Timothy

Re: [Worg] Proposing a few CSS changes

[Adam Porter]

[-- Attachment #1: Type: text/plain, Size: 884 bytes --]

Hi Timothy,

Timothy <tecosaur@gmail.com> writes:

> Great! I’ve just taken a peek and it’s a clear improvement in my eyes
> 🙂.

:)

>> Note that, after I made the other changes, the links scattered around
>> the page clashed very badly with the nice “Org green” and black theme,
>> so I adjusted them as well (as detailed in the commit message).  I tried
>> using “Org green” for the link text, but it seemed too low-contrast, as
>> well as a bit distracting while reading, so I opted to use colorize just
>> the underlines, and to make the link text green when hovering.
>
> I just had a look at this, and I tried a darkened green (#08402e). I think this
> may be the best option.

That may be a good choice, yes.  But I almost feel like, with the
headers also being a very similar green, it's a bit of "green overload"
in some areas.  For example, this screenshot:


[-- Attachment #2: links.png --]
[-- Type: image/png, Size: 101287 bytes --]

[-- Attachment #3: Type: text/plain, Size: 645 bytes --]


But in other places it does look nice, so I won't protest if you want to
make that change.  :)

>> Note as well that I ended up using 48em for the content width due to the
>> unicorn logo in the corner being covered up by wider content than that
>> (in a half-1080p-width browser window, which seems like an important use
>> case to consider).
>
> We should probably update the “angry unicorn” to the logo on the homepage,
> perhaps <https://orgmode.org/resources/img/org-mode-unicorn.svg> or a simplified
> version.

Well, personally, I don't mind having "the original" there.  :)  But I'll
leave that decision to you and others.

Thanks.

Re: [Worg] Proposing a few CSS changes

[Eric S Fraga]

Looks good (on both large monitor and on my phone).  Thank you!
-- 
: Eric S Fraga via Emacs 28.0.50, Org 9.5-g9a4a24
: Latest paper written in org: https://arxiv.org/abs/2106.05096

Re: [Worg] Proposing a few CSS changes

[Thomas S. Dye]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Looks good (on both large monitor and on my phone).  Thank you!

+1

--
Thomas S. Dye
https://tsdye.online/tsdye