docs/webview: Write up how we use px and rem (and no em), and why.

We had the key elements of this reasoning, between the existing
version of this doc and the commit messages for 6ef229e,
ebaffb4, and 3dc7fee.  But when seeking to explain it
recently I found that not all the dots were connected, plus the
writeups were scattered through those several places.

So, write up the reasoning more fully and in one, editable, place.
Also add its bottom line to our nascent style guide.

Author: gnprice

docs/background/layout.md

@@ -5,6 +5,7 @@
 The units of measurement in UI layout are a bit complicated.  When doing any
 UI work, it's important to understand them anyway.
 
+
 ### Display size; logical pixels
 
 Dimensions in React Native are written without explicit units, and are
@@ -42,6 +43,7 @@ pixels on the display.  As a result, our code should basically never know
 about this scaling factor.  Where it is important to know is for us humans,
 inspecting and debugging layouts.
 
+
 ### Font/text size
 
 Separately, the user can adjust the size of text.  This is also in system
@@ -56,6 +58,12 @@ measured in `sp` while the rest of a layout is in `dp`.
 On iOS, the term for this is "Dynamic Type".  Details would be good to add
 here.
 
+
+### In the WebView
+
+See [webview.md](webview.md).
+
+
 ### Further reading
 
 The Material Design guidelines have a helpful [page about units and

docs/background/webview.md

@@ -1,44 +1,115 @@
 # WebView
 
-The message list styles arecontrolled by the `css.js` file, which
-gives us more powerful set of styles compared to the ones we use
-in our React Native code.
+We show the message list inside a browser environment, in a `WebView`
+component.
 
-## Sizes: px vs rem
 
-We use two units 'px' and 'rem'. We differentiate between their use
-for one strict purpose:
+## Styling
 
-* any element in 'px' will not change its size
-* any element in 'rem' will change its size proportionally with the
-root font size of the `html` element
+The message list styles are controlled by two files:
+`src/webview/css/css.js` and `src/webview/static/base.css`.
 
-If you are curious why we would use 'rem' (and why not 'em') read
-further these two articles:
-https://j.eremy.net/confused-about-rem-and-em/
-https://zellwk.com/blog/rem-vs-em/
 
-## Usability considerations
+### Lengths: px vs rem; no em
 
-Units like 'rem's are very frequently used for 'padding' and 'margin'
-in web design. A style like `padding: 1rem;` has the wonderful property
-of looking proportional to the font size, which might change depending
-on different media queries.
+For CSS lengths in the webview, we use the two units `px` and
+`rem`.  We do not use `em`.
 
-We are explicitly not following that practice. After some research, it
-become apparent that, naturally, different priorities exist on mobile.
-With font increase, we will try to keep all other UI elements the same
-size, not because this looks better (it doesn't) but because there is
-not enough space on the screen for such luxuries.
+Specifically, we use `rem` for the size of text, and `px` for
+everything else.  See our [style guide](../style.md) for more details.
 
-For maximum usability and smart screen real-estate usage:
+We do this because it implements in the webview the same behavior
+that's standard for native mobile apps, and because it's important for
+accessibility.  Detailed reasoning is below.
 
-Things that should not change size:
- * buttons
- * padding, margin
- * loading indicators
- * avatars
+Background on what each unit means:
 
-Things that should change size:
- * text
- * elements that should be treated like text (emoji!)
+* A length in `px` is exactly that many [logical pixels](layout.md).
+  In particular this is an approximately constant physical length
+  across devices, and across different system settings: `16px` is
+  approximately 0.1 inches or 2.5mm, and might be as large as about
+  0.13 inches or 3.2mm.
+
+* A length in `rem` scales with the font size at the root of the
+  document, which in turn [scales with](layout.md) the system
+  font-size settings.  By default `1rem` equals `16px`, but depending
+  on user settings it can be a bit smaller or much, much larger.  In
+  particular, many visually impaired users set their devices to a very
+  large font size.
+
+* A length in `em` scales with the font size of the current element or
+  its parent (depending on what property it's used for.)  This is like
+  `rem` except it depends additionally on `font-size` values found
+  elsewhere in the stylesheet.
+
+
+### Why `rem` and not `em`
+
+When `em` is used, it becomes complicated to understand what length
+the value found in a given rule actually works out to -- and the
+answer can even vary for a single rule as applied in different places.
+
+In a website with a variety of design contexts where different kinds
+of text appear with different sizes, and with detailed text style
+rules that appear across multiple kinds of text, that variation can
+potentially be a useful feature.  This is what `em` is for and why
+some web-design advice urges using it.
+
+In our message list, there is just one kind of text that appears at
+significant length: the message bodies.  Other text comes in small
+pieces, and in highly structured contexts like timestamp pills or the
+emoji + counts in reactions.  There are few if any style rules
+affecting text in multiple contexts (and if there are, that's likely a
+bug), which means little to no benefit to be had from letting a rule's
+meaning vary across contexts.  Meanwhile, using `em` means a major
+cost in comprehensibility as the reader has to do a global search for
+`font-size` rules that might apply to ancestors of the given element.
+
+At one time (before [6ef229e42][]) our CSS had a chaotic mixture of
+values in `em` and `px`.  Because of the variation in `font-size` and
+correspondingly in the meaning of `em`, this meant that to understand
+what a given length meant, and what the constraints were on changing
+it, was a complicated matter.  That in turn made it hard to make
+changes, and easy to introduce small bugs.
+
+[6ef229e42]: https://github.com/zulip/zulip-mobile/commit/6ef229e42
+
+For more discussion, see the following articles:
+* https://zellwk.com/blog/rem-vs-em/ (detailed background, and
+  examples of several approaches)
+* https://j.eremy.net/confused-about-rem-and-em/ (advises `em`, for
+  web design with a variety of kinds of complex text)
+
+
+### Why (mostly) `px` and not `rem`
+
+Typical advice for web design is to use `rem` or `em` for nearly all
+lengths.  This means that when the font size grows or shrinks, not
+only the text but the whole layout scales with it, including padding,
+margin, and images.
+
+But on mobile, if you go to a device's settings and [change the font
+size](layout.md), you'll find this is not at all what apps do.  When
+you make the font size giant, the text in an app grows with it -- but
+everything that *isn't* text stays the same.  Icons in the UI; user
+avatars; padding around text; padding or margin between elements;
+indentation of items in a list; all stay exactly the same.  This is
+true on Android and iOS, and of flagship apps from Google, Apple,
+Facebook, and others.
+
+On Android, an app implements this behavior by using `sp` for text and
+`dp` for everything else, following the upstream recommendation; see
+our [layout.md](layout.md).
+
+In a webview, this translates to using `rem` for text and `px` for
+everything else.  So that's what we do.
+
+To understand why this is the standard on mobile, consider that mobile
+screens are often small and the layouts don't have a lot of room to
+spare.  If when a user doubled their text size to make it readable for
+them, that also doubled all the spacing in the UI... then that could
+leave very little room for the actual text they wanted to read.  See
+our commits [ebaffb456][] and [3dc7fee83][] for discussion.
+
+[ebaffb456]: https://github.com/zulip/zulip-mobile/commit/ebaffb456
+[3dc7fee83]: https://github.com/zulip/zulip-mobile/commit/3dc7fee83

docs/style.md

@@ -2,6 +2,7 @@
 
 (This is not at all complete.)
 
+
 ## Git: commits, commit messages
 
 ### See also
@@ -74,3 +75,36 @@ basically amounts to an @-mention!  Other common lines include
     Tested-by:
 
 and there's no fixed list; people invent others.
+
+
+## WebView: HTML, CSS, JS
+
+### Styling/CSS
+
+**Use `px`, sometimes `rem`, no `em`:** For CSS lengths in the
+webview, we use `rem` for text and `px` for everything else.
+We do not use `em`.
+
+We use these units like so:
+
+* All values for `margin` or `padding`, and most `width`, `height`,
+  and other lengths, are in `px`.
+
+* Lengths for *the size of text* are in `rem`.  This includes almost
+  all values for `font-size`.  In a few cases another length property,
+  like `width` or `height`, is describing something that functions as
+  text -- e.g., an emoji -- and this includes those cases.
+
+Put another way: the following scale with the font size:
+* text, and
+* a few text-like elements like emoji,
+
+while everything else is independent of font size, including:
+* avatars,
+* UI icons, and
+* all padding and margin, including padding around text.
+
+We do this because it implements in the webview the same behavior
+that's standard for native mobile apps, and because it's important for
+accessibility.  For detailed background and rationale, see
+[docs/background/webview.md](background/webview.md#styling).