# The 25 Golden Rules Behind GoldenVizR

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.

## Completeness

Rule | What GoldenVizR checks
--- | ---
1 Clear title | Whether the chart has a meaningful title that names the subject or message.
2 Axis labels | Whether x and y axes are labeled clearly enough to understand values and units.
3 Missing values and gaps | Whether missing data or visible gaps are detected in the plotted data.
4 Legend clarity | Whether mapped color, fill, shape, or other legend aesthetics have usable legend text.
5 Source and context | Whether a caption, subtitle, or source gives enough context for interpretation.
6 Annotation for key message | Whether obvious gaps, missing values, or key-message needs are supported by annotation.

## Readability

Rule | What GoldenVizR checks
--- | ---
7 Readable text | Whether explicit text sizes are likely to remain readable.
8 Accessible color choices | Whether the number of encoded colors is likely to remain distinguishable.
9 Avoid clutter | Whether layer count, mark count, and geom variety suggest unnecessary clutter.
10 Grid and guide balance | Whether grid and guide styling is balanced rather than heavy or absent when needed.
11 Consistent formatting | Whether scale and formatting metadata are internally consistent.
12 Appropriate chart type | Whether the selected geom is plausible for the mapped data, such as avoiding lines over unordered categories.
13 Readable scale labels | Whether axis and scale labels are present and readable.
14 Overplotting management | Whether dense point layers may require transparency, aggregation, jitter, or binning.
15 Direct labeling when useful | Whether direct labels could reduce legend lookup for small multi-series charts.
16 Visual hierarchy | Whether title and text signals create a clear visual hierarchy.

## Integrity

Rule | What GoldenVizR checks
--- | ---
17 Truthful scale | Whether scale choices appear truthful for the chart type.
18 No distorted baseline | Whether bar, column, or area charts preserve a zero baseline when required.
19 Avoid misleading encodings | Whether high-risk encodings, such as area or size mappings, may mislead.
20 Handle outliers honestly | Whether numeric outliers are present and whether they appear acknowledged.
21 Proportional areas | Whether area-like encodings are used proportionally.
22 Uncertainty when needed | Whether uncertainty layers such as ribbons, error bars, or smoothing intervals are present when needed.
23 Avoid cherry picking | Whether limited scales without context may hide relevant data selection.
24 Respect data granularity | Whether the visual form respects the data granularity, such as avoiding connected lines for unordered categories.
25 Neutral framing | Whether title and subtitle avoid loaded or manipulative framing words.

## Programmatic rule registry

The same rule order is available from R:

    library(GoldenVizR)
    goldenviz_rules()

    ##     id       family                        rule
    ## 1   R1 Completeness                 Clear title
    ## 2   R2 Completeness                 Axis labels
    ## 3   R3 Completeness     Missing values and gaps
    ## 4   R4 Completeness              Legend clarity
    ## 5   R5 Completeness          Source and context
    ## 6   R6 Completeness  Annotation for key message
    ## 7   R7  Readability               Readable text
    ## 8   R8  Readability    Accessible color choices
    ## 9   R9  Readability               Avoid clutter
    ## 10 R10  Readability      Grid and guide balance
    ## 11 R11  Readability       Consistent formatting
    ## 12 R12  Readability      Appropriate chart type
    ## 13 R13  Readability       Readable scale labels
    ## 14 R14  Readability     Overplotting management
    ## 15 R15  Readability Direct labeling when useful
    ## 16 R16  Readability            Visual hierarchy
    ## 17 R17    Integrity              Truthful scale
    ## 18 R18    Integrity       No distorted baseline
    ## 19 R19    Integrity  Avoid misleading encodings
    ## 20 R20    Integrity    Handle outliers honestly
    ## 21 R21    Integrity          Proportional areas
    ## 22 R22    Integrity     Uncertainty when needed
    ## 23 R23    Integrity        Avoid cherry picking
    ## 24 R24    Integrity    Respect data granularity
    ## 25 R25    Integrity             Neutral framing