---
title: "The 25 Golden Rules Behind GoldenVizR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{The 25 Golden Rules Behind GoldenVizR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

GoldenVizR checks charts against 25 practical visualization rules inspired by
The 25 Golden Rules of Data Viz course at goldenviz.org.

The rules are grouped into three families:

- **Completeness**: the chart contains enough information to be understood.
- **Readability**: the chart can be read without unnecessary effort.
- **Integrity**: the chart avoids misleading scale, encoding, or framing choices.

```{r rules-table, echo=FALSE}
registry <- GoldenVizR::goldenviz_rules()
rules <- data.frame(
  Family = registry$family,
  Rule = paste(seq_len(nrow(registry)), "-", registry$rule),
  `What GoldenVizR checks` = c(
    "Whether the chart has a meaningful title that names the subject or message.",
    "Whether x and y axes are labeled clearly enough to understand values and units.",
    "Whether missing data or visible gaps are detected in the plotted data.",
    "Whether mapped color, fill, shape, or other legend aesthetics have usable legend text.",
    "Whether a caption, subtitle, or source gives enough context for interpretation.",
    "Whether obvious gaps, missing values, or key-message needs are supported by annotation.",
    "Whether explicit text sizes are likely to remain readable.",
    "Whether the number of encoded colors is likely to remain distinguishable.",
    "Whether layer count, mark count, and geom variety suggest unnecessary clutter.",
    "Whether grid and guide styling is balanced rather than heavy or absent when needed.",
    "Whether scale and formatting metadata are internally consistent.",
    "Whether the selected geom is plausible for the mapped data, such as avoiding lines over unordered categories.",
    "Whether axis and scale labels are present and readable.",
    "Whether dense point layers may require transparency, aggregation, jitter, or binning.",
    "Whether direct labels could reduce legend lookup for small multi-series charts.",
    "Whether title and text signals create a clear visual hierarchy.",
    "Whether scale choices appear truthful for the chart type.",
    "Whether bar, column, or area charts preserve a zero baseline when required.",
    "Whether high-risk encodings, such as area or size mappings, may mislead.",
    "Whether numeric outliers are present and whether they appear acknowledged.",
    "Whether area-like encodings are used proportionally.",
    "Whether uncertainty layers such as ribbons, error bars, or smoothing intervals are present when needed.",
    "Whether limited scales without context may hide relevant data selection.",
    "Whether the visual form respects the data granularity, such as avoiding connected lines for unordered categories.",
    "Whether title and subtitle avoid loaded or manipulative framing words."
  ),
  check.names = FALSE
)

family_order <- c("Completeness", "Readability", "Integrity")
family_rows <- split(rules, factor(rules$Family, levels = family_order))

rule_family_table <- function(family_name, family_data) {
  htmltools::tags$section(
    class = "gv-rules-family",
    htmltools::tags$h2(class = "gv-rules-family-title", family_name),
    htmltools::tags$table(
      class = "gv-rules-table",
      htmltools::tags$colgroup(
        htmltools::tags$col(class = "gv-rules-col-rule"),
        htmltools::tags$col(class = "gv-rules-col-checks")
      ),
      htmltools::tags$thead(
        htmltools::tags$tr(
          htmltools::tags$th("Rule"),
          htmltools::tags$th("What GoldenVizR checks")
        )
      ),
      htmltools::tags$tbody(
        lapply(seq_len(nrow(family_data)), function(i) {
          htmltools::tags$tr(
            htmltools::tags$td(
              htmltools::tags$span(class = "gv-rule-number", sub(" - .*", "", family_data$Rule[[i]])),
              htmltools::tags$span(class = "gv-rule-name", sub("^[0-9]+ - ", "", family_data$Rule[[i]]))
            ),
            htmltools::tags$td(family_data[["What GoldenVizR checks"]][[i]])
          )
        })
      )
    )
  )
}

htmltools::tagList(Map(rule_family_table, names(family_rows), family_rows))
```

## Programmatic rule registry

The same rule order is available from R:

```{r rules-registry}
library(GoldenVizR)
goldenviz_rules()
```