Doc: rewrite Solarized comparison

Author: jan-warchol

whats-wrong-with-solarized.md

@@ -1,94 +1,103 @@
-How Selenized improves upon Solarized
-=====================================
+How Selenized improves on Solarized
+===================================
 
-Selenized is based on [Solarized color
-palette](http://ethanschoonover.com/solarized), which was designed by Ethan
-Schoonover.  Solarized has some great features, but it does have a few issues
-as well (this is why I have created Selenized) - they are discussed below.
+I really liked the design principles behind Solarized - it has some great
+features. However, it has a few problems as well, which Selenized solves:
 
+* [Confusing accent colors](#better-accent-colors)
+* [Not enough contrast](#slightly-higher-contrast)
+* [Dark version is too dark](#better-lightness)
+* [Hacky implementation in terminals](#better-terminal-compatibility)
 
 
-Problems with accent colors
----------------------------
 
-<!-- TODO: add colorwheel image -->
+Better accent colors
+--------------------
 
-Some accent colors in Solarized are a bit too similar to each other.
-For example, magenta can be easy to confuse with red on some displays and in
-some situations.  Yes, they *are* different, but they should be less ambiguous.
-Similarly, green is too close to yellow.
+Some accent colors in Solarized are confusing or too similar to each other:
+
+* green is too much like yellow (looks like olive)
+* orange looks almost like red
+* magenta too close to red as well
+* violet is easy to confuse with blue
+
+![Solarized and Selenized colorwheel comparison](https://i.imgur.com/1AsC3pS.png)
+
+This is less of a problem on high-end, color-calibrated displays, but on a
+regular screen (like the one on my ThinkPad from a couple years ago) it can be
+really difficult to tell some colors apart. Selenized makes the differences
+clearer.
 
 <!-- TODO: add picture with git log -->
 
-In fact, green in Solarized is not like typical green - it is more like olive.
-Personally I prefer more "traditional" green.
 
-Selenized uses different, less ambiguous hues than Solarized (although the
-difference may seem small, especially on cheap displays).
 
+Slightly higher contrast
+------------------------
+
+Ethan says on Solarized website that he had tested it in a variety of lighting
+conditions.  However, in practice I have encountered numerous situations when
+Solarized readability was not satisfactory. This is confirmed by [Web Content
+Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/),
+which requires contrast of [4.5 for AA
+grade](https://www.w3.org/TR/WCAG21/#contrast-minimum) and [7.0 for AAA
+grade](https://www.w3.org/TR/WCAG21/#contrast-enhanced):
+
+| color/color combination      | Solarized                    | Selenized dark               | Selenized black                                 |
+| ---------------------------- | ---------                    | --------------               | ---------------                                 |
+| main content (foreground)    | 4.75 - AA :heavy_check_mark: | 6.07 - AA :heavy_check_mark: | 9.05 - AAA :heavy_check_mark::heavy_check_mark: |
+| fg on bg highlight           | 4.11 - :thinking:\*          | 5.04 - AA :heavy_check_mark: | 7.81 - AAA :heavy_check_mark::heavy_check_mark: |
+| secondary content (comments) | 2.79 - AA :x:                | 3.23 - :thinking:\*          | 3.97 - :thinking:\*                             |
+| red (darkest accent color)   | 3.25 - :thinking:\*          | 3.71 - :thinking:\*          | 4.79 - AA :heavy_check_mark:                    |
 
+:thinking:\* _WCAG says that contrast of 3.0 is acceptable if the font has
+sufficient size and weight. 3.0 is also the minimum contrast for body text
+required by ISO-9241-3._
 
-Problems with contrast
-----------------------
+<!-- sele vs sola screenshot -->
 
-Ethan says on Solarized website that he had tested Solarized on a variety of
-monitors in different lighting conditions.  However, I have encountered
-situations when readability of Solarized was not satisfactory - especially on
-mediocre displays (maybe Ethan only used high-quality screens for testing?).
-Selenized has slightly increased contrast (50 "Lab units" instead of 45) and
-looks good on all displays, expensive and cheap.
+Contrast in Selenized remains moderately low, but it is significantly more
+readable in poor lighting than Solarized.
 
-Another, more serious problem is that Solarized dark works well when used all
-by itself, but it is too dark to be placed next to a high-contrast window that
-has black text on white background (e.g. a pdf or a browser).  Here is a
-screenshot of Solarized dark next to Wikipedia:
+
+
+Better lightness
+----------------
+
+Solarized dark may work well when used all by itself, but it's *too dark* when
+placed next to a window with high-contrast content:
 
 ![Solarized next to black&white Wikipedia](http://i.imgur.com/UlOxerG.png)
 
-This problem is more visible when someone uses Solarized dark for snippets of
-code on a high-contrast website, like this:
+This is even more visible when Solarized dark is used for a code snippets on
+a website with white background:
 
 ![short code sample with Solarized](http://i.imgur.com/vStjfca.png)
 
-Selenized solves this problem by increasing contrast and making the whole dark
-variant lighter:
+Selenized dark is slightly lighter and doesn't have this problem:
 
 ![Selenized next to black&white Wikipedia](http://i.imgur.com/OX2Ce2r.png)
 
 ![short code sample with Selenized](http://i.imgur.com/fm8Orae.png)
 
 
 
-Problems with implementation
-----------------------------
+Better terminal compatibility
+-----------------------------
 
-One of the features of Solarized is that both light and dark variants can be
-constructed from the same set of 16 colors.  This is a nice property, but
-implementing it in case of terminal emulators requires using a weird mapping of
-color codes to actual color values.
+Solarized puts both light and dark variants in one color palette, resulting in
+a weird mapping of ANSI color codes to actual color values. For example,
+Solarized maps color code meant for bright/bold green to "base 01" (greyish
+shade used for comments):
 
 ![color code assignment - solarized](http://i.imgur.com/Rn3yhw1.png)
 
-For example, you can see that color code traditionally used for bright/bold
-green is used by Solarized for "secondary content" (i.e. color used for
-comments), and so on. The result is that many command line programs will
-produce weird-looking or unreadable output unless they are configured with
-specific Solarized settings.  See [this
-issue](https://github.com/altercation/solarized/issues/220) and [this Stack
-Overflow
-question](http://stackoverflow.com/questions/14093554/vim-solarized-on-os-x-terminal-app-incorrect-colors)
-for an example.
+Because of that many command line programs will produce strange or unreadable
+output (see examples
+[here](https://github.com/altercation/solarized/issues/220) and
+[here](http://stackoverflow.com/questions/14093554/vim-solarized-on-os-x-terminal-app-incorrect-colors)).
 
-Selenized adheres to standard meanings of terminal color codes:
+Selenized keeps standard meaning of terminal color codes:
 
 ![color code assignment - selenized](http://i.imgur.com/h6Rog02.png)
 
-Some programs may need adjustments to work well with Selenized, but such issues
-happen less frequently.
-
-Apart from terminals, I think that the decision to use exactly the same accent
-colors in both light and dark variants of Solarized was wrong.  This constraint
-forces the lightness of the accent colors to be a compromise, rather than
-picking optimal lightness for dark and light versions separately - and the
-benefits of this solution are, in my opinion, negligible.
-