Docs: Docs site theme does not have sufficient color contrast/link contrast

[machikoyasuda]

The Benefits docs site theme, which uses Cal-ITP's default docs theme, is not color contrast sufficient in a few areas:

• The nav bar color background
• The footer text
• The links on white background
• The links should be underlined or visibly distinguished w/o color
• Gray comments in code blocks

I believe the changes need to be made upstream, in this repo, https://github.com/cal-itp/mkdocs-template, but I wanted to document the bug in Benefits first.

To Reproduce

Steps to reproduce the behavior:

1. Go to '...'
2. Run a11y tests

Expected behavior

Ideas:

• Replace the bright blue with Cal-ITP blue for background and links
• Change the footer to be black on white text
• Change the links to be underlined by default

• Change it upstream here https://github.com/cal-itp/mkdocs-template so all docs get these changes
• There's a Dark Mode too
• Hopefully it's easy to make these color and link changes w/o too much overriding

[thekaveman]

The settings initially come from https://github.com/cal-itp/mkdocs-template, but that is only a template repo for creating other repos, so making changes there won't automatically reflect out to all other docs sites.

These are OOTB mkdocs-material styles, but there are a lot of customization options: https://squidfunk.github.io/mkdocs-material/customization/

It would be nice to normalize the look and feel with the app itself.

[machikoyasuda]

I wanted to see if and how I could get the docs site WCAG 2.0 AA compliant with as little code as possible. Here's how far I got, to fix all the color contrast and link issues:

mkdocs.yml: set up custom css

   palette:
     - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: blue
-      accent: amber
+      primary: custom
+      accent: custom
       toggle:
         icon: material/toggle-switch-off-outline
         name: Switch to dark mode
     - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: blue
-      accent: amber
+      primary: custom
+      accent: custom
       toggle:
         icon: material/toggle-switch
         name: Switch to light mode
@@ -42,6 +40,7 @@ plugins:

 extra_css:
   - https://use.fontawesome.com/releases/v5.13.0/css/all.css
+  - stylesheets/extra.css

docs/stylesheets/extra.css: use cal-itp blue and white, set underlines on links

[data-md-color-scheme="default"] {
  --md-primary-fg-color: #045b86;
  --md-primary-fg-color--light: #045b86;
  --md-primary-fg-color--dark: #045b86;
  --md-footer-fg-color: hsla(0, 0%, 100%, 1);
  --md-footer-fg-color--light: hsla(0, 0%, 100%, 1);
  --md-footer-fg-color--lighter: hsla(0, 0%, 100%, 1);
  --md-footer-bg-color: hsla(0, 0%, 0%, 1);
  --md-footer-bg-color--dark: hsla(0, 0%, 0%, 1);
  --md-code-hl-comment-color: #0071ce;
  --md-typeset-a-color: #000000;
}

a {
  text-decoration: currentColor underline dotted auto;
}

.md-tabs__link {
  opacity: 1;
  font-weight: bold;
  text-decoration: none;
}

Looks like this: