From dd353aac1525f4e62188ace1b07b48c25bc8c477 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Fri, 10 May 2024 16:02:11 -0500 Subject: [PATCH] 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. --- NEWS.md | 1 + pkgdown/_pkgdown.yml | 2 ++ vignettes/accessibility.Rmd | 57 +++++++++++++++++++++++++++++++++++++ vignettes/customise.Rmd | 4 ++- vignettes/pkgdown.Rmd | 4 +++ 5 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 vignettes/accessibility.Rmd diff --git a/NEWS.md b/NEWS.md index dc994b462a..0e7c1e20d6 100644 --- a/NEWS.md +++ b/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). diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 1cecac5087..7d3366acc5 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -21,6 +21,7 @@ template: primary: "#0054AD" border-radius: 0.5rem btn-border-radius: 0.25rem + danger: "#A6081A" includes: in_header: @@ -33,6 +34,7 @@ articles: navbar: ~ contents: - customise + - accessibility - linking - search - metadata diff --git a/vignettes/accessibility.Rmd b/vignettes/accessibility.Rmd new file mode 100644 index 0000000000..d582adc4ac --- /dev/null +++ b/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 . + +* 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) +``` +```` \ No newline at end of file diff --git a/vignettes/customise.Rmd b/vignettes/customise.Rmd index 0286bc923e..ea6448bbd7 100644 --- a/vignettes/customise.Rmd +++ b/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). diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index a989c53a73..7d7e3324dd 100644 --- a/vignettes/pkgdown.Rmd +++ b/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`.