Improve readability of nested highlights in PDFs

In PDFs, highlights are drawn in an otherwise-transparent text layer _on
top_ of a canvas which displays the text that the user sees. Therefore
highlights reduce the contrast of the text below and more than two
levels starts to make the text very difficult to read.

The ideal solution would be to draw the highlights below the text, but
that's not trivial.

As a simple step to improve the situation, make nested highlights that
are 3+ levels deep transparent. This limits the amount of contrast
reduction that overlapping highlights can cause.

In web pages, the highlights are drawn _behind_ the text, so contrast is
not reduced as much, but the same change is applied there for a
consistent experience and also because it is easier to implement.

Partially addresses:

 - https://github.com/hypothesis/client/issues/1995
 - https://github.com/hypothesis/client/issues/408

src/styles/annotator/highlights.scss

@@ -37,21 +37,33 @@
       @include screen-reader-only;
       content: ' annotation end ';
     }
-  }
 
-  .hypothesis-highlight .hypothesis-highlight {
-    background-color: var.$highlight-color-second;
-  }
+    // Give a highlight inside a larger highlight a different color to stand out.
+    & .hypothesis-highlight {
+      background-color: var.$highlight-color-second;
 
-  .hypothesis-highlight .hypothesis-highlight .hypothesis-highlight {
-    background-color: var.$highlight-color-third;
-  }
-}
+      // In document viewers where the highlight is drawn _on top of_ the text
+      // (eg. PDF.js) too many nested highlights can make the underlying text unreadable.
+      // Therefore we make any highlights that are 3+ levels deep transparent.
+      //
+      // In web pages highlights are drawn _underneath_ the text so nested
+      // highlights don't reduce text contrast as much, but we still only use
+      // two levels of highlight color for consistency.
+      //
+      // See https://github.com/hypothesis/client/issues/1995.
+      & .hypothesis-highlight {
+        background-color: transparent;
+      }
+    }
 
-.hypothesis-highlight.hypothesis-highlight-focused {
-  background-color: var.$highlight-color-focus !important;
+    // When an annotation card is hovered in the sidebar, the corresponding
+    // highlights are shown with a "focused" color.
+    &.hypothesis-highlight-focused {
+      background-color: var.$highlight-color-focus !important;
 
-  .hypothesis-highlight {
-    background-color: transparent !important;
+      .hypothesis-highlight {
+        background-color: transparent !important;
+      }
+    }
   }
 }

src/styles/variables.scss

@@ -152,7 +152,6 @@ $zindex-tooltip: 20;
 $bucket-bar-width: 22px;
 $highlight-color: rgba(255, 255, 60, 0.3);
 $highlight-color-second: rgba(206, 206, 60, 0.4);
-$highlight-color-third: rgba(192, 192, 49, 0.4);
 $highlight-color-focus: rgba(156, 230, 255, 0.5);
 $top-bar-height: 40px;
 $group-list-width: 280px;