Wikipedia:Manual of Style/Accessibility/Data tables tutorial

This tutorial is a guideline which, as part of Wikipedia's Manual of Style, is intended to assist those creating data tables (or more often lists) in ensuring the content is accessible to all. For more info on how to create and edit tables, see Help:Table.

Guidelines on this page are ordered primarily by priority, then difficulty. The priority levels are determined by the Accessibility Success Criteria rankings A, AA, and AAA (in descending order of importance as accessibility considerations) of the World Wide Web Consortium (W3C) Web Content Accessibility Guidelines (WCAG) 2.0. The difficulty indicates if it seems easy or not for Wikipedia users to comply to the guidelines.

Guidelines here essentially follow WCAG 2.0's approach, and some additional reputable sources, like WebAIM, when relevant. A review by an accessibility expert was necessary to ensure WCAG 2.0 was interpreted correctly; this review was made in September 2010.

Overview of basics

• Priority: high (accessibility level: A)
• Difficulty: easy (the syntax is fairly simple and editors get used to it; the layout might change users' habits)

Wikitext:

{| class="wikitable"
|+ caption text
|-
! scope="col" | column header 1
! scope="col" | column header 2
! scope="col" | column header 3
|-
! scope="row" | row header 1
| data 1 || data 2
|-
! scope="row" | row header 2
| data 3 || data 4
|}

Produces:

caption text

column header 1	column header 2	column header 3
row header 1	data 1	data 2
row header 2	data 3	data 4

Caption ( |+ )

A caption is a table's title, describing its nature.

Row and column headers ( ! )

Like the caption, these help present the information in a logical structure to visitors. The headers help screen readers render header information about data cells. For example, header information is spoken prior to the cell data, or header information is provided on request.

Scope of headers (scope="col" and scope="row")

This clearly identifies headers as either column headers or row headers respectively.

Layout of table headers

As can be seen in the example above, row headers are formatted by default as bold, centered and with a darker background. This is the common behavior across the Internet, and the default rendering in most browsers. In some circumstances it might be desirable to apply a style customized for a specific case. The class plainrowheaders will apply left-aligned and normal-weight formatting so that editors do not feel the need to override the header formatting with inline CSS declarations for each cell. Used by itself, plainrowheaders will make headers appear similar to unmodified data cells, except for the darker background.

To use plainrowheaders, place it (like wikitable) in the class attribute at the beginning of the table. The example below shows an unbolded, left-aligned row header with a custom larger font style:

Wikitext:

{| class="wikitable plainrowheaders"
|-
! scope="col" | column header 1
! scope="col" | column header 2
|-
! scope="row" style="font-size: larger;" | row header
| data
|}

Produces:

column header 1	column header 2
row header	data

Proper table captions and summaries

Table markup provides for both captions and summaries, both of great utility for making tables accessible. The caption provides a descriptive heading for the table and the summary provides a "nutshell" of its content. If you like, you can think of them as analogous, respectively, to a journal paper's title and its abstract.

Caption

• Priority: high (accessibility level: A)
• Difficulty: easy (the syntax is fairly simple and already in use; the layout slightly changes users' habits)

All data tables need a table caption that succinctly describes what the table is about. It plays the role of a table heading, and is recommended as a best practice. You would usually need some kind of heading or description introducing a new table anyway, and this is what the caption feature exists for. Table captions are made with |+. A caption can be styled with CSS, and may include wikilinks, reference citations, etc. It may be explicitly put to the left like other Wikipedia headings with style="text-align: left;" (a good idea especially on wide tables). Captions are not used for layout tables (these are deprecated on Wikipedia as well as more broadly, but some editors temporarily resort to them until later editors wikicode whatever it was they were trying to achieve.)

A temporary case for not using the |+ caption is in certain situations when using a collapsible table. As of September 2010, the "[hide]" / "[show]" collapse control has to be inside a table header (until the collapsibility script is improved), and it must be large enough to contain it. If the table has no header, or only a very small header, a common solution has been to put the caption text in a table header to which the collapse controller may attach.

Example of a proper caption from Tobin Bell#Filmography:

Bell's television appearances and roles

Title	Year	Role	Notes
The Equalizer	1988		Episode: "The Day of the Covenant"
Perfect Witness	1989	Dillon	TV film
Alien Nation	1990	Brian Knox	Episode: "Crossing the Line"

Captions should be concise; if the table needs an extended introduction, provide one in normal article prose, then provide a simpler caption. However, table captions consisting of a single word like "Actor", "Film" or "Television" – as in a previous revision of Tobin Bell's filmography – are inadequate, as they are not descriptive enough.

Avoiding column headers in the middle of the table

• Priority: high (accessibility level: A)
• Difficulty: medium (requires large changes to tables, editors seem reluctant to split tables, needs more testing and feedback)

Do not place column headers in the middle of a table to visually separate the table. For example, a screen reader reading the cell "Stuttgart, Germany" might associate the cell with the following headers: "Venue, Representing Soviet Union, Representing Belarus". Three headers are read aloud. The first and the third are correct and expected. But "Representing Soviet Union" does not apply to the lower half of the table, and a machine does not understand that. Thus, a machine will not be able to associate header and cells correctly, and will provide misleading information about the table structure to the user.

In most cases, the easier solution is to split the table into several sub-tables with explanatory sub-headings (second example).

Column headers: bad example

From Vasiliy Kaptyukh and produced by {{AchievementTable}}:

Year	Competition	Venue	Position	Notes
Representing Soviet Union
1985	European Junior Championships	Cottbus, East Germany	3rd
1986	World Junior Championships	Athens, Greece	3rd
1990	European Championships	Split, Yugoslavia	4th	63.72 m
Representing Belarus
1993	World Championships	Stuttgart, Germany	7th	61.64 m
1995	World Championships	Gothenburg, Sweden	3rd	65.88 m
	IAAF Grand Prix Final	Monte Carlo, Monaco	4th

Other similar examples can be found at Yvonne van Gennip, Masters Athletics World Records and Comparison of layout engines (Cascading Style Sheets)#Selectors.

Column headers: good example 1

The first solution where the table is split in several sub-tables.

Vasiliy Kaptyukh's achievements representing Soviet Union

Competition	Year	Venue	Position	Notes
European Junior Championships	1985	Cottbus, East Germany	3rd
World Junior Championships	1986	Athens, Greece	3rd
European Championships	1990	Split, Yugoslavia	4th	63.72 m

Vasiliy Kaptyukh's achievements representing Belarus

Competition	Year	Venue	Position	Notes
World Championships	1993	Stuttgart, Germany	7th	61.64 m
World Championships	1995	Gothenburg, Sweden	3rd	65.88 m
IAAF Grand Prix Final		Monte Carlo, Monaco	4th

Column headers: good example 2

An alternative which takes a bit more time to implement is to add a column for the representation.

Vasiliy Kaptyukh's achievements

Competition	Year	Representing	Venue	Position	Notes
European Junior Championships	1985	Soviet Union	Cottbus, East Germany	3rd
World Junior Championships	1986	Soviet Union	Athens, Greece	3rd
European Championships	1990	Soviet Union	Split, Yugoslavia	4th	63.72 m
World Championships	1993	Belarus	Stuttgart, Germany	7th	61.64 m
World Championships	1995	Belarus	Gothenburg, Sweden	3rd	65.88 m
IAAF Grand Prix Final	1995	Belarus	Monte Carlo, Monaco	4th

Complex tables

In contrast with simple tables, which only have headers spanning one column (! scope="col" | ) or one row (! scope="row" | ), some headers may span multiple columns or rows with the use of the colspan or rowspan attributes. To clearly define relationships and avoid accessibility issues, use ! scope="colgroup" colspan="2" | when a column header spans two columns and ! scope="rowgroup" rowspan="2" | when a row header spans two rows, adjusting the number if spanning more.

Wikitext:

{| class="wikitable"
|-
! scope="col" rowspan="2" | column header 1
! scope="col" rowspan="2" | column header 2
! scope="colgroup" colspan="2" | column header group
|-
! scope="col" | column header 3
! scope="col" | column header 4
|-
! scope="rowgroup" rowspan="2" | row header group
! scope="row" | row header 1
| data || data
|-
! scope="row" | row header 2
| data || data
|-
! scope="row" colspan="2" | row header 3
| data || data
|}

Produces:

column header 1	column header 2	column header group
		column header 3	column header 4
row header group	row header 1	data	data
	row header 2	data	data
row header 3		data	data

For tables with headers that are more complex, it is recommended to simplify the table or split it up into smaller tables. When this isn't possible, you have to associate each cell to their respective header(s) using the id and headers attributes instead of scope. On the headers, set the id to an unspaced value that is unique on the page. On the cells that are described by headers, set the "headers" to a spaced list of the describing "id" values in an order that a screen reader should read them. For example, the following markup has the "Company" header describing the "ABC" company (! id="col1" | Company and | headers="col1" | ABC).

Below is an example of a complex table with headers that aren't visually clear, but uses id and headers instead of scope to associate column and row headers to individual cells. Again, it is recommended to simplify the table so headers are visually clear by splitting it into a "d" and "e" table if possible where the text in the "d" and "e" cells are moved to each table's caption.

Wikitext:

{| class="wikitable"
|-
! id="a" | a
! id="b" | b
! id="c" | c
|-
! colspan="3" id="d" | d
|-
! id="w" headers="d a" | w (d a)
| headers="d b w" | d b w
| headers="d c w" | d c w
|-
! id="x" headers="d a" | x (d a)
| headers="d b x" | d b x
| headers="d c x" | d c x
|-
! colspan="3" id="e" | e
|-
! id="y" headers="e a" | y (e a)
| headers="e b y" | e b y
| headers="e c y" | e c y
|-
! id="z" headers="e a" | z (e a)
| headers="e b z" | e b z
| headers="e c z" | e c z
|}

Produces:

a	b	c
d
w (d a)	d b w	d c w
x (d a)	d b x	d c x
e
y (e a)	e b y	e c y
z (e a)	e b z	e c z

Images and color

Note that colors and images with contrast conforming to accessibility requirements will print nicely in grayscale as an induced effect (among other benefits).

Images

• Priority: high (accessibility level: A)
• Difficulty: unknown (needs more testing and feedback for a precise rating)

Images inside a table should meet the general requirements in Wikipedia:Alternative text for images. However, small icons are the principal case encountered in a table. They fall into two categories:

1. icons of symbols ought to have minimal alt text that conveys the same information as the icon (example: if indicates an increase it has |alt=increase);
2. decorative icons (icons carrying no information or associated with a text providing similar information) need to be unlinked and have an empty alt text (|link=|alt=). When they are not able to be unlinked, a minimal alt text will suffice.

Note that images in headers can be particularly annoying for screen reader users if they are badly handled. If the image does not comply with the above criteria, the filename will be part of the header title. The filename will be read aloud in every cell under the header containing the icon. The alt text will also be repeated like the filename, which can also be a nuisance if it is irrelevant to the subject or is too long.

Color

• Priority: high (accessibility level: A)
• Difficulty: medium (needs testing and feedback for a precise rating)

Colors inside a table should meet the requirements for color.

• Color contrast – measured by the free Color Contrast Analyser – needs to be sufficient.
• A very simple tool that can be helpful for choosing contrasting colours is Color Oracle, a "free color blindness simulator for Windows, Mac and Linux".

But more importantly, information should not be conveyed by color alone. Information should also be available textually. A footnote or a textual sign can also be used to show a cell has a particular meaning.

Bad uses of color

From Fiscal calendar#Chart of Different Fiscal Years:

By country

Country	Purpose	J	F	M	A	M	J	J	A	S	O	N	D	J	F	M	A	M	J	J	A	S	O	N	D
Australia
Canada

Good uses of color

Note: This is an example of using color rather than of providing accessible tables. Having the table caption in a table header instead produces a non-accessible table.

Legend: cells marked with "✓" are included in the fiscal year.

Fiscal years by country

Country	Purpose	J	F	M	A	M	J	J	A	S	O	N	D	J	F	M	A	M	J	J	A	S	O	N	D
Australia								✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
Canada					✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓

Fiscal years by country

Country	Purpose	J	F	M	A	M	J	J	A	S	O	N	D	J	F	M	A	M	J	J	A	S	O	N	D
Australia								1st of July to 30th of June
Canada					1st of April to 31st of March

From Dwain Chambers (with improved table caption and structure; but the original use of color is good):

Dwain Chambers competition record

Competition	Year	Venue	Position	Event
European Championships	1998	Budapest, Hungary	2nd	100 metres
IAAF World Cup		Johannesburg, South Africa	3rd	100 metres
Commonwealth Games		Kuala Lumpur, Malaysia	1st	4×100 metres relay
European Cup	1999	Paris, France	1st	100 metres
IAAF World Championships		Seville, Spain	3rd	100 metres
			2nd	4×100 metres relay

Nested data tables

• Priority: high (accessibility level: A)
• Difficulty: unknown (not yet rated)

Nested tables can be confusing for screen reader users, however with correct usage they can be navigated as well as any other coding approach to the desired display.

The key principle in their design and implementation is to maintain normal flow, i.e. to ensure that the ordering of the content in the page code matches the order in which the content is to be presented. This also applies to other coding approaches, such as divs with CSS styling, or rowspan and colspan HTML cell attributes.

Nesting data tables with header cells also makes it difficult for assistive readers to parse them sensibly, and should be avoided.

Nesting tables may be the most appropriate method where cells of the parent table are to be subdivided with uneven internal row or column breaks. Note that each table must begin on a new line.

In the following example, nested tables are used to display sub-tables of varying cell heights:

Wikitext:

{| class="wikitable"
|
{| class="wikitable"
| Insert 1up
|-
| Insert 1down:<br>&nbsp;<br>Taller than insert 1up
|}
|
{| class="wikitable"
| &nbsp;<br>Insert 2<br>full height<br>&nbsp;
|}
|
{| class="wikitable"
| Insert 3up<br>&nbsp;<br>Tall cell here
|-
| Insert 3down
|}
|
{| class="wikitable"
| Insert 4up<br>&nbsp;
|-
| Insert 4down<br>Same as above
|}
|}

Produces:

Insert 1up Insert 1down:   Taller than insert 1up

Insert 2 full height

Insert 3up   Tall cell here Insert 3down

Insert 4up   Insert 4down Same as above

By comparison, using rowspan would not only need careful juggling of the positions and values but would break normal flow, splitting up each data subset and even causing Insert 3down and Insert 4down to be read in the wrong order:

Wikitext:

{| class="wikitable"
| Insert 1up
| rowspan="4" | full height
| rowspan="3" | Insert 3up<br>&nbsp;<br>Tall cell here
| rowspan="2" | Insert 4up
|-
| rowspan="3" | Insert 1down:<br>&nbsp;<br>Taller than insert 1up
|-
| rowspan="2" | Insert 4down<br>Same as above
|-
| Insert 3down
|}

Produces:

Insert 1up	full height	Insert 3up   Tall cell here	Insert 4up
Insert 1down:   Taller than insert 1up
			Insert 4down Same as above
		Insert 3down

CSS also has table display properties which can be applied to other elements such as divs, and could be used to create the layout with correct normal flow. But it requires a custom stylesheet defining the various classes of substitute entity. Moreover, it breaks the formal separation of HTML structure vs. CSS styling by using the styling language to render the correct structure onscreen. It is unnecessary and is not recommended.

Resources

Additional information can be found at Data tables tutorial/Internal guidelines‎‎. However, this guideline is not meant to be enforced, and only serves as a resource for members of WikiProject Accessibility.

These are examples of tables read aloud by screen readers. They may be useful as concrete examples to show to the community, when the community has difficulty in understanding how an accessible table benefits a screen reader user.

• Table using SCOPE attributes (NVDA using the Crystal voice from NaturalSoft)
• Table using ID attribute (NVDA using the default eSpeak voice)