Accessibility guidance checklist

Purpose

This vignette shows you how {a11ytables} meets accessibility best practice.

Checklists

This page shows how the features of the {a11ytables} package meet the Analysis Function’s ‘Making spreadsheets accessible: checklist of the basics’ guidance.

The assessments in the table below are based on generating an unedited output from a typical {a11ytables} workflow, i.e. use create_a11ytable() to make an a11ytable that’s passed to generate_workbook() and then written with openxlsx::saveWorkbook().

There are several self-assessed indicators used in the ‘status’ column of the tables below:

  • ‘met’ means that {a11ytables} contains a feature (or the absence of a feature) to help meet the requirement
  • ‘user’s responsibility’ means that the user must make a decision about how to meet the requirement
  • ‘partly’ means that {a11ytables} contains a feature to help meet the requirement, but the user may need to provide additional input
  • ‘not applicable’ means the checklist item does not need to be met due to the way in which {a11ytables} works

Tables

Description Essential? Status Explanation
Mark up tables Yes Met Provided automatically by generate_workbook()
Give tables meaningful names No Met Unique table names are generated from the tab_titles argument in create_a11ytable()
Remove merged cells, split cells and nested tables Yes Met {a11ytables} doesn’t create these features
Remove blank rows and columns within tables Yes Partly/user’s responsibility A warning is supplied to a user if cells in the table are blank but no explanation has been provided in the blank_cells column of the provided a11ytables object
All tables should have one tagged header row Yes Met R’s data.frame class only allows for one header row, which must have unique names; the header row is tagged when marked-up as a table
Wrap text within cells Yes Met generate_workbook() wraps content by default; there’s a simple check in {a11ytables} to widen a column if it contains long strings
Avoid adding filters and freeze panes No Met Filters and freezing aren’t supported by {a11ytables}
Only leave cells with no data empty in certain circumstances Yes User’s responsibility The user should describe why there are blank cells in the blank_cells column of their a11ytables object
Avoid hiding rows or columns No Met Hiding isn’t supported by {a11ytables}
Columns should be a sensible width No Partly {a11ytables} uses a fixed default column width for data tables (16), which is doubled (32) if the length of the content exceeds a threshold number of characters (50)

Footnotes

Description Essential? Status Explanation
Do not use symbols or superscript to signpost to notes Yes Met/user’s responsibility Notes are detected automatically as digits in square brackets; superscript is not supported by {a11ytables}
Use the word ‘note’ when referring to footnotes No User’s responsibility Notes are detected in the form ‘[note 1]’; the user should be consistent about this wording
Avoid putting note markers in specific cells No User’s responsibility Columns named ‘Notes’ and note markers in column headers are detected, the user should not put these elsewhere
Put note text in a notes table on a notes worksheet No Met create_a11ytable() expects the sheet_type ‘notes’

Formatting

Description Essential? Status Explanation
All written content needs to meet the accessibility guidelines No User’s responsibility {a11ytables} does not check the validity of user-supplied text
Links must be accessible Yes User’s responsibility {a11ytables} does not check the validity of user-supplied text
Format text to make it accessible No Met generate_workbook() auto-formats the text
All worksheets should have descriptive titles which are properly tagged and formatted Yes Partly/user’s responsibility {a11ytables} does not check user-supplied text nor data; the package handles formatting but not yet mark-up for headings
Avoid using symbols in general No User’s responsibility {a11ytables} does not check the validity of user-supplied text
Do not use headers and footers, floating text boxes or floating toolbars Yes Met These features aren’t supported by {a11ytables}
Do not use visual devices to divide data regions No Met Colours and patterns aren’t supported by {a11ytables}
Do not use a background fill No Met Fills aren’t supported by {a11ytables}
Do not use colour as the only way to convey a message Yes Met Colour is not supported by {a11ytables}
When using colour for emphasis check the contrast Yes Not applicable Colour is not supported by {a11ytables}, so a check is not required
Avoid images in spreadsheets No Met Images aren’t supported by {a11ytables}
Remove macros No Met Macros aren’t supported by {a11ytables}

Structure

Description Essential? Status Explanation
Give worksheets unique names or numbers Yes User’s responsibility Supply tab_titles to create_a11ytable(), which gives a warning if any names match
Remove blank worksheets Yes Met create_a11ytable() will error if expected argument content is missing
Use cells in column A wisely Yes Met generate_workbook() inserts the sheet title, table count, notes statement, source statement and tables into column A by default
Position tables against the left-hand edges of each sheet Yes Met generate_workbook() inserts automatically the tables into column A
Avoid putting content below a table No Met generate_workbook() adds information to rows above tables only
Avoid worksheets with multiple tables No Met The package supports only one table per sheet (for now)

Before publishing

Description Essential? Status Explanation
Run a spelling and grammar check Yes User’s responsibility These checks aren’t supported by {a11ytables}; the user should check using their own software
Use the accessibility checker No User’s responsibility These checks aren’t supported by {a11ytables}; the user should check using their own software
Add document information Yes User’s responsibility Not yet possible with {a11ytables}; users must do this manually
Ensure the cursor is in cell A1 of the first worksheet when doing your final save Yes Met Occurs automatically

Contribute

To contribute, please add an issue or a pull request after reading the code of conduct and contributing guidance.