Create accessibility vignette (#2518)

Including advice fixing the colour contrast issue caused by using the danger colour on a light navbar background (and apply that advice to pkgdown itself)

Fixes #2344. Fixes #2283.

Author: hadley

NEWS.md

@@ -1,5 +1,6 @@
 # pkgdown (development version)
 
+* New `vignette("accessibility")` describes what manual tasks you need to perform to make your site as accessible as possible (#2344).
 * `build_reference()` now automatically translates `--`, `---`, ``` `` ```, and `''` to their unicode equivalents (#2530).
 * Tweaked navbar display on mobile so that long titles in drop downs (e.g. article titles) are now wrapped, and the search input spans the full width (#2512).
 * `build_reference()` now supports `\Sexpr[results=verbatim]` (@bastistician, #2510).

pkgdown/_pkgdown.yml

@@ -21,6 +21,7 @@ template:
     primary: "#0054AD"
     border-radius: 0.5rem
     btn-border-radius: 0.25rem
+    danger: "#A6081A"
   includes:
     in_header:
       <script defer data-domain="pkgdown.r-lib.org,all.tidyverse.org" src="https://plausible.io/js/plausible.js"></script>
@@ -33,6 +34,7 @@ articles:
   navbar: ~
   contents:
   - customise
+  - accessibility
   - linking
   - search
   - metadata

vignettes/accessibility.Rmd

@@ -0,0 +1,57 @@
+---
+title: "Accessibility"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{accessibility}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+pkgdown automates as many accessibility details as possible, so that your package website is readable by as many people as possible. This vignette describes the additional details that can't be automated away and you need to be aware of.
+
+```{r setup}
+library(pkgdown)
+```
+
+## Theming
+
+* If you adjust any colours from the default theme (including the syntax highlighting theme), you should double check that the contrast between the background and foreground doesn't make any text difficult to read. A good place to start is running a representative page of your site through <https://wave.webaim.org>.
+
+* The default colour of the development version label makes a slightly too low contrast against the pale grey background of the navbar. This colour comes from the bootstrap "danger" colour, so you can fix it by overriding that variable in your `_pkgdown.yml`:
+
+    ```yaml
+    template:
+      bootstrap: 5
+      bslib:
+        danger: "#A6081A"
+    ```
+
+* If you use custom navbar entries that only display an icon, make sure to also use the `aria-label` field to provide an accessible label that describes the icon.
+
+    ```yaml
+    cran:
+      icon: fab fa-r-project
+      href: https://cloud.r-project.org/package=pkgdown
+      aria-label: View on CRAN
+    ```
+
+## Images
+
+To make your site fully accessible, the place where you are likely to need to do the most work is adding alternative text to any images that you create. Unfortunately, there's currently no way to do this for plots you generate in examples, but you can and should add alternative text to plots in vignettes using the `fig.alt` chunk option:
+
+````{verbatim}
+```{r}
+#| fig.alt: >
+#|   Histogram of time between eruptions for Old Faithful. 
+#|   It is a bimodal distribution with peaks at 50-55 and 
+#|   80-90 minutes.
+hist(faithful$waiting)
+```
+````

vignettes/customise.Rmd

@@ -43,6 +43,8 @@ Upgrading to Bootstrap 5 has a low chance of breaking your site unless you were
 There are two ways to change the visual style of your site from `_pkgdown.yml`: using a pre-packaged bootswatch theme or customising theme variables with [bslib](https://rstudio.github.io/bslib/).
 The following sections show you how.
 
+Please note that pkgdown's default theme has been carefully optimised to be accessible, so if you make changes, make sure that to also read `vignette("accessibility")` to learn about potential accessibility pitfalls.
+
 ### Bootswatch themes
 
 The easiest way to change the entire appearance of your website is to use a [Bootswatch theme](https://bootswatch.com):
@@ -93,7 +95,7 @@ template:
 You can customise other components by setting more specific bslib variables, taking advantage of inheritance where possible.
 For example, `table-border-color` defaults to `border-color` which defaults to `gray-300`.
 If you want to change the colour of all borders, you can set `border-color`; if you just want to change the colour of table borders, you can set `table-border-color`.
-You can find a full list of variables in `vignette("bs5-variables", package = "bslib")`.
+You can find a full list of variables in the [bslib docs](https://rstudio.github.io/bslib/articles/bs5-variables/index.html).
 
 Theming with bslib is powered by `bslib::bs_theme()` and the `bslib` field is a direct translation of the arguments to that function.
 As a result, you can fully specify a bslib theme using the `template.bslib` field, making it easy to share YAML with the `output.html_document.theme` field [of an R Markdown document](https://rstudio.github.io/bslib/articles/theming/index.html).

vignettes/pkgdown.Rmd

@@ -75,6 +75,10 @@ Current available translations are:
 -   `tr`: Turkish
 -   `zh_CN`: Chinese (simplified)
 
+## Accessibility
+
+pkgdown's defaults work to ensure that your site is accessible to as many people as possible. But there are some accessibilty issues that only a human can solve, so make sure to also read `vignette("accessibility")` to learn about them.
+
 ## Home page
 
 The contents of the home page are automatically generated from `index.md` or `README.md`.