Package 'a11yviz'

Description

Returns a named numeric vector of alpha values for common chart roles. Use them when setting ⁠alpha =⁠ in ⁠ggplot2::geom_*()⁠ or plotly traces. Alpha lowers the effective contrast a viewer sees, so verify the composited contrast with a11y_check_palette() when the choice matters.

Usage

a11y_alpha_presets()

Value

Named numeric vector with elements raw_points, overlay_point, labels, fill, ci_ribbon, ci_band.

Examples

a11y_alpha_presets()
a11y_alpha_presets()[["overlay_point"]]

Description

Introspects a ggplot or plotly object and emits a sentence scaffold with chart type, axis labels, ranges, and group counts pre-filled. A bracketed placeholder marks where the substantive trend description belongs. Pass the edited string to a11y_alt_text() to attach it.

Usage

a11y_alt_template(p)

Arguments

Value

Character scalar.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  p <- ggplot(mtcars, aes(wt, mpg, color = factor(cyl))) + geom_point()
  a11y_alt_template(p)
}

Description

For plotly objects, sets the figure-level aria-label and a hidden description div. For ggplot, attaches the alt text as an attribute that Quarto renders as ⁠<img alt="...">⁠.

Usage

a11y_alt_text(p, text)

Arguments

Value

The object with alt text attached.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  p <- ggplot(mtcars, aes(mpg, wt)) + geom_point()
  a11y_alt_text(p, "Scatter of car weight against fuel economy.")
}

Description

Pair with a CSS rule that defines .screen-reader-only (see a11y_css()).

Usage

a11y_announce(text)

Arguments

Value

Character scalar containing HTML.

See Also

a11y_css()

Examples

a11y_announce("Loading results, please wait")

Description

Generates a semantic aria-label value combining an action, element type, and optional context. Intended for Shiny UI elements (buttons, inputs).

Usage

a11y_aria_label(element_type, action, context = NULL)

Arguments

Value

Character scalar suitable for aria-label.

Examples

a11y_aria_label("button", "analyze", "readability")
a11y_aria_label("input", "search")

Description

Union of a11y_audit_chart() and a11y_audit_doc(). Prefer the split functions when one scope is enough.

Usage

a11y_audit(p, level = "AA")

Arguments

Value

Data frame with columns criterion, check, status, note. Join to a11y_rubric() for principle, guideline, and threshold.

Description

Filters an audit data frame to rows with status todo or ok – the decisions a chart author has to make. Drops rows handled by helpers, rows that belong to the host document, and rows marked manual / n/a.

Usage

a11y_audit_actionable(audit)

Arguments

Value

Data frame with the same columns as audit, filtered.

Description

Returns the chart-relevant rows from the WCAG 2.1 audit: alt text, redundant group encoding, text contrast, text size, non-text contrast, hover/focus, and (at AAA) stronger text contrast.

Usage

a11y_audit_chart(p, level = "AA")

Arguments

Value

Data frame with columns criterion, check, status, note.

Description

Returns the host-page rows from the WCAG 2.1 audit: heading hierarchy, text resizing, reflow, body text spacing, and visible keyboard focus.

Usage

a11y_audit_doc(level = "AA")

Arguments

Value

Data frame with columns criterion, check, status, note.

Description

Returns a sentence counting how many checks need a decision, how many pass, and how many are already handled.

Usage

a11y_audit_summary(audit)

Arguments

Value

Length-1 character vector.

Description

Validates a candidate alt-text string for informative content. Decorative elements should pass decorative = TRUE and use alt="" in markup. Companion to a11y_alt_text(), which attaches alt text to a plot object; this function validates a string before attaching.

Usage

a11y_check_alt_text(
  alt_text,
  element_type = "image",
  decorative = FALSE,
  min_length = 10
)

Arguments

Value

TRUE if valid; FALSE with a warning otherwise.

See Also

a11y_alt_text()

Examples

a11y_check_alt_text("Bar chart showing word frequency", "plot")
suppressWarnings(a11y_check_alt_text("", "plot"))
a11y_check_alt_text("", "icon", decorative = TRUE)

Description

Scans a file for three heading defects: (a) skipped heading levels (e.g., ⁠##⁠ followed by ⁠####⁠), (b) empty headings, (c) non-descriptive headings (text shorter than min_chars). These violate WCAG 2.1 Success Criteria 1.3.1 (Info and Relationships), 2.4.6 (Headings and Labels), and 2.4.10 (Section Headings).

Usage

a11y_check_headings(path, min_chars = 3)

Arguments

Value

Data frame with one row per issue, columns line, level, text, issue. Empty data frame if no issues.

Examples

## Not run: 
  a11y_check_headings("paper.qmd")

## End(Not run)

Description

Bins point coordinates from geom_point layers to a bins x bins grid in data space and reports the fraction of points that share a cell with another point. Treat as a render-resolution proxy for Success Criterion 1.3.1 (information must remain perceivable). When overlap is non-zero, alpha may be considered, but composited contrast must clear 3:1 per Success Criterion 1.4.11.

Usage

a11y_check_overlap(p, bins = 100)

Arguments

Value

List with total, obscured, fraction, recommendation.

Description

Computes the contrast ratio of every color against a reference background and reports whether each meets the WCAG threshold (4.5:1 for AA, 7:1 for AAA). When alpha < 1, contrast is computed against the alpha-composited rendered color – the color the viewer actually sees. Works on any palette – viridis, RColorBrewer, plotly's discrete sequences, or a custom hex vector.

Usage

a11y_check_palette(colors, bg = "#ffffff", level = "AA", alpha = 1)

Arguments

Value

Data frame with columns color, bg, alpha, rendered, ratio, status.

Examples

a11y_check_palette(c("#000000", "#cccccc", "#ff0000"))
a11y_check_palette(c("#0072B2"), bg = c("#ffffff", "#1a1a1a"), level = "AA-large")
a11y_check_palette(c("#0072B2", "#D55E00"), alpha = 0.7, level = "AA-large")

Description

Distinguishability drops fast above seven categories even in CVD-safe palettes; consider faceting, aggregation, or a sequential / ordinal encoding instead.

Usage

a11y_check_palette_size(n, max = 7)

Arguments

Value

Named list with n, max, status ("ok" / "todo"), note.

Examples

a11y_check_palette_size(5)
a11y_check_palette_size(12)

Description

Computes Flesch-Kincaid Grade Level and Flesch Reading Ease for the supplied text. Pure base R with a syllable-count heuristic; no external dependencies. Maps to WCAG 2.1 Success Criterion 3.1.5 (Reading Level, AAA).

Usage

a11y_check_readability(text)

Arguments

Value

Data frame with one row and columns sentences, words, syllables, flesch_kincaid_grade, flesch_reading_ease.

Examples

a11y_check_readability("The cat sat on the mat. The dog ran away.")

Description

For every pair of colors in the palette, computes the WCAG relative-luminance contrast ratio – the same formula used by a11y_check_palette(). Pairs below min_ratio (default 3.0, the WCAG 2.1 Success Criterion 1.4.11 "Non-text Contrast / Graphical Objects" threshold) are flagged. Two data marks of similar colors may fail this – viewers cannot tell them apart.

Usage

a11y_check_separability(colors, min_ratio = 3)

Arguments

Value

Data frame with columns from, to, ratio, status.

Examples

a11y_check_separability(c("#1B9E77", "#D95F02", "#7570B3"))

Description

Positive tabindex values above the natural document flow create unpredictable keyboard navigation. WCAG 2.1.1 (Keyboard) recommends tabindex = 0 (natural order) or tabindex = -1 (focusable but skipped).

Usage

a11y_check_tabindex(tabindex = 0)

Arguments

Value

TRUE if valid; FALSE with a warning if non-numeric or > 100.

Examples

a11y_check_tabindex(0)
a11y_check_tabindex(-1)
suppressWarnings(a11y_check_tabindex(999))

Description

Returns the filesystem path to a11yviz.css, an accessible stylesheet that makes plotly, DT, DiagrammeR, and static plot images theme-aware and applies WCAG-aligned defaults for contrast, focus, and text spacing. Use it in Quarto via ⁠css:⁠, in Shiny via tags$link(), or copy it into a project's ⁠www/⁠.

Usage

a11y_css(mode = c("default", "shiny"))

Arguments

Value

Character path (default) or character vector of paths (shiny).

Examples

basename(a11y_css())
length(a11y_css("shiny"))

Description

Reads the bundled CSS file(s) returned by a11y_css() and concatenates them as a single string. Useful for embedding inline in Quarto via ⁠<style>⁠ tags or in Shiny via tags$style().

Usage

a11y_css_contents(mode = c("default", "shiny"))

Arguments

Value

Character scalar of CSS source.

Examples

nchar(a11y_css_contents())

Description

Extracts deterministic plot context (chart type, axes, ranges, group counts) and passes it to the user's backend function, which calls any LLM provider and returns the alt-text string. Result is attached to the plot via a11y_alt_text() when attach = TRUE.

Usage

a11y_describe(p, backend, attach = TRUE)

Arguments

Details

The package itself depends on no LLM SDK; the caller supplies the transport. See examples for OpenAI, Gemini, and Ollama backends.

Value

The plot with alt text attached, or the string itself.

Examples

## Not run: 
  openai_backend <- function(context) {
    prompt <- paste(
      "Write one-sentence WCAG 1.1.1 alt text.",
      "State chart type, axes, and key trend."
    )
    auth <- paste("Bearer", Sys.getenv("OPENAI_API_KEY"))
    res <- httr::POST(
      "https://api.openai.com/v1/chat/completions",
      httr::add_headers(Authorization = auth),
      body = list(
        model = "gpt-4o-mini",
        messages = list(
          list(role = "system", content = prompt),
          list(role = "user",
               content = jsonlite::toJSON(context, auto_unbox = TRUE))
        )
      ),
      encode = "json"
    )
    httr::content(res)$choices[[1]]$message$content
  }
  p |> a11y_describe(backend = openai_backend)

## End(Not run)

Description

Wraps plotly::ggplotly() with a11y_layout() and forwards alt text attached via a11y_alt_text(). Strips redundant chart titles. Reserve for the interactive supplement; a static ggplot with alt text is the more accessible default.

Usage

a11y_ggplotly(
  gg,
  level = "AA",
  palette = NULL,
  alt = NULL,
  tooltip = c("x", "y"),
  strip_title = TRUE,
  ...
)

Arguments

Value

A plotly object.

Examples

if (requireNamespace("ggplot2",        quietly = TRUE) &&
    requireNamespace("plotly",         quietly = TRUE) &&
    requireNamespace("palmerpenguins", quietly = TRUE)) {
  library(ggplot2)
  p <- ggplot(na.omit(palmerpenguins::penguins),
              aes(flipper_length_mm, body_mass_g,
                  color = species, shape = species)) +
    geom_point() +
    scale_color_a11y("dark2_8") +
    theme_a11y("AA")
  p <- a11y_alt_text(p, "Penguin body mass vs flipper length by species.")
  pl <- a11y_ggplotly(p)
  inherits(pl, "plotly")
}

Description

Sets fonts, axis styling, hover-label colors, legend position, and an accessible categorical colorway. Targets WCAG 2.1 contrast (1.4.3, 1.4.6, 1.4.11) and resizability (1.4.4). Font sizes are package defaults, not WCAG-mandated minimums. Returns the plotly object so it can stay in a ⁠|>⁠ chain.

Usage

a11y_layout(p, level = "AA", palette = "dark2_8")

Arguments

Value

Modified plotly object.

Description

Adds only the non-destructive moves: attaches alt text, and raises the base text size to the WCAG minimum only when the current size is below it. Palette, theme, legend, and geom aesthetics stay intact. Suitable for retrofitting charts with an existing visual; theme_a11y() and scale_a11y() are the greenfield path. Pair with a11y_audit_chart() to surface remaining gaps (color-only encoding, missing alt, hover styling).

Usage

a11y_minimum(p, alt = NULL, level = "AA")

Arguments

Value

The chart with alt text attached (if supplied) and base text size raised to the level threshold when it was below.

Description

Returns hex codes for a color-vision-aware categorical palette. Most palettes are runtime wrappers around RColorBrewer::brewer.pal() so the authoritative colors stay in their source package.

Usage

a11y_palette(name = "dark2_8", n = NULL, bg = NULL)

Arguments

Value

Character vector of hex codes (e.g., "#1B9E77"). For sequential gradients, see a11y_palette_seq().

Examples

a11y_palette("dark2_8")
a11y_palette("aaa_5")
a11y_palette("dark2_8", n = 4)

Description

Returns the low/mid/high anchor colors for a diverging gradient. Most palettes resolve at runtime from RColorBrewer. ⁠*_dual⁠ variants pick mid-saturation Brewer positions whose endpoints clear non-text 3:1 on both white and ⁠#1a1a1a⁠ dark backgrounds. coolwarm_aaa is a custom built-in whose endpoints both clear AAA on white only.

Usage

a11y_palette_div(name = "rdbu")

Arguments

Value

Named list with elements low, mid, high (hex codes for the diverging anchors). To materialize an N-step gradient, pass the list to a color interpolator (e.g., grDevices::colorRampPalette()).

Examples

a11y_palette_div("rdbu")
a11y_palette_div("rdbu_dual")

Description

Returns the source spec, resolved colors, and WCAG metadata for a discrete palette. For continuous palettes, see a11y_palette_div() and a11y_palette_seq().

Usage

a11y_palette_info(name = "dark2_8")

Arguments

Value

Named list with name, colors, safe_on, purpose, notes, plus the source spec fields.

Examples

a11y_palette_info("aaa_5")

Description

Lists discrete, diverging, and sequential palettes in one data frame.

Usage

a11y_palette_list(type = NULL)

Arguments

Value

Data frame with columns name, type, source, n, safe_on, purpose. n is NA for continuous palettes. For the notes field of a single palette, call a11y_palette_info().

Examples

a11y_palette_list()
a11y_palette_list(type = "diverging")

Description

Returns a viridisLite spec (option, begin, end, direction) for a sequential gradient. Use directly with ⁠ggplot2::scale_*_viridis_c()⁠ or via scale_fill_a11y_seq(). Pass ⁠n =⁠ to materialize hex codes.

Usage

a11y_palette_seq(name = "cividis", n = NULL)

Arguments

Value

Named list with elements option, begin, end, direction – a viridisLite specification, NOT a color vector. Pass ⁠n =⁠ to materialize hex codes.

Examples

a11y_palette_seq("cividis")
a11y_palette_seq("viridis", n = 7)

Description

Plotly ships several discrete categorical sequences (from plotly.js). This helper computes WCAG contrast statistics for each one against a reference background so users can pick a sequence that passes their contrast bar.

Usage

a11y_plotly_sequences(bg = "#ffffff", level = "AA")

Arguments

Value

Data frame with one row per sequence: name, n, min_ratio, median_ratio, n_pass, pct_pass.

Examples

a11y_plotly_sequences()
a11y_plotly_sequences(level = "AAA")

Description

Returns the chart-relevant subset of WCAG 2.1 success criteria, with the AA / AAA threshold and the a11yviz function that addresses it. Joins to a11y_audit() on the criterion column.

Usage

a11y_rubric(level = NULL)

Arguments

Value

Data frame with columns criterion, name, level, threshold_aa, threshold_aaa, a11yviz_function. Pass any criterion value to a11y_wcag_url() for the spec link.

Examples

a11y_rubric()
a11y_rubric(level = "AAA")

Description

Renders the swatches of a built-in palette and overlays each color's contrast ratio against bg, plus a pass/fail label for level.

Usage

a11y_show_palette(name = "dark2_8", bg = "#ffffff", level = "AA")

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  a11y_show_palette("dark2_8")
}

Description

Returns the spacing ratios specified in WCAG Success Criterion 1.4.12 (Text Spacing, Level AA). All values are multiples of the font size.

Usage

a11y_text_spacing_ratios()

Value

Named numeric vector with line_height, paragraph, letter, word.

Examples

a11y_text_spacing_ratios()
a11y_text_spacing_ratios()[["line_height"]]

Description

Returns a deep link to the W3C WCAG 2.1 specification entry for one or more success criteria.

Usage

a11y_wcag_url(criterion)

Arguments

Value

Character vector of URLs the same length as criterion. Returns the spec root URL for unrecognised values.

Examples

a11y_wcag_url("1.4.3")
a11y_wcag_url(c("1.1.1", "2.4.7", "4.1.3"))

Description

Applies the most common transforms in one call: theme plus color and fill palettes for ggplot, or layout plus palette for plotly.

Usage

make_a11y(p, level = "AA", palette = "dark2_8", alt = NULL)

Arguments

Value

The transformed object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  p <- ggplot(mpg, aes(class, fill = drv)) + geom_bar()
  make_a11y(p, palette = "dark2_8", alt = "Vehicle classes by drivetrain.")
}

Description

Opens a Shiny app comparing default ggplot2 output against the accessible theme, palette, and alt-text helpers, with a per-criterion WCAG audit. Requires shiny, bslib, ggplot2, and DT; missing packages are flagged at launch.

Usage

run_app(host = "127.0.0.1", port = 8000, launch_browser = TRUE, ...)

Arguments

Value

Invisibly, the return value of shiny::runApp().

Examples

if (interactive()) run_app()

Description

Categorical palettes that meet WCAG 1.4.1 (Use of Color) by being distinguishable to viewers with color vision differences.

Usage

scale_color_a11y(palette = NULL, level = "AA", ...)

scale_fill_a11y(palette = NULL, level = "AA", ...)

Arguments

Value

A ggplot2 scale.

Examples

if (requireNamespace("ggplot2",        quietly = TRUE) &&
    requireNamespace("palmerpenguins", quietly = TRUE)) {
  library(ggplot2)
  pg <- na.omit(palmerpenguins::penguins)
  ggplot(pg, aes(flipper_length_mm, body_mass_g, color = species)) +
    geom_point() + scale_color_a11y()
  ggplot(pg, aes(species, fill = island)) +
    geom_bar() + scale_fill_a11y("set2_8")
}

Description

ggplot2 scales for diverging gradients with anchor colors sourced from a11y_palette_div().

Usage

scale_color_a11y_div(palette = "rdbu", ...)

scale_fill_a11y_div(palette = "rdbu", ...)

Arguments

Value

A ggplot2 scale.

Description

ggplot2 scales for sequential viridisLite gradients sourced from a11y_palette_seq(). The default "cividis" remains readable in greyscale and spans the full lightness range.

Usage

scale_color_a11y_seq(palette = "cividis", ...)

scale_fill_a11y_seq(palette = "cividis", ...)

Arguments

Value

A ggplot2 scale.

Description

Adds a ggplot2::theme that applies WCAG 2.1 contrast settings plus the package's recommended font sizes. Compose with + like any other theme. Title, axis title, and legend sit at the body floor (12 pt AA / 14 pt AAA); axis tick text drops 2 pt below.

Usage

theme_a11y(level = "AA", base_family = "", dark = FALSE)

Arguments

Value

A theme object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)
  ggplot(mtcars, aes(mpg, wt)) + geom_point() + theme_a11y()
}