abbr design pattern
Purpose
Use the abbr-design-pattern when you have localized, language, or design-specific human readable information that you want to markup and also provide a more globally human and machine readable alternative.
- Authors MUST NOT use the abbr-design-pattern to hide data.
- The contents of the
<abbr>tag'stitleattribute MUST be both human-readable and human-listenable (e.g. for screenreaders), and SHOULD use a globally/internationally human readable format. - For dates and times, authors SHOULD use the HTML5
<time>element instead of<abbr>. (ed: Once common tools like chrome-extensions, h2vx, operator all support the HTML5 time element, let's upgrade this statement to a MUST).
How to use it
- enclose the preferred local human readable text that you want to make globally human & machine readable with
<abbr> - add the relevant microformats property names to the
<abbr>tag'sclassattribute - add a
titleattribute to theabbrelement with the globally human & machine readable data as the value - The end result MUST be human readable & listenable, when reading/speaking the abbr element's contents and its surroundings and when reading/speaking the abbr element's title attribute with its surrounding text.
Example
The date-design-pattern formally encodes globally human readable ISO dates into an abbr element. Per the documentation/research on the date-design-pattern page, ISO8601 dates, e.g. of the form YYYY-MM-DD, are the most globally/internationally date format.
Note: that dates and times SHOULD be marked up with the HTML5 time element. These examples illustrate both span/abbr markup for pre-HTML5 tools, and time element support for HTML5-capable tools.
Before:
The party is on the 10th. After:
The party is on <abbrclass="dtstart"title="2005-10-10">the 10th</abbr>. Better (with HTML5 time instead of abbr)
The party is on <timeclass="dtstart"datetime="2005-10-10">the 10th</time>. You could also use the abbr-design-pattern to markup colloquial time references, but those should also use the HTML5 time element, e.g.
Before:
The party is at 10 o'clock. After:
The party is at <abbrclass="dtstart"title="10:00">10 o'clock</abbr>. Better (with HTML5 time instead of abbr)
The party is at <timeclass="dtstart"datetime="10:00">10 o'clock</time>. Alternative presentations
Note that the following are all equivalent, to a microformat parser:
<spanclass="dtstart">2007-05-01</span><abbrclass="dtstart"title="2007-05-01">1 May 2007</abbr><abbrclass="dtstart"title="2007-05-01">1st May 2007</abbr>. <abbrclass="dtstart"title="2007-05-01">May 1st 2007</abbr>. <abbrclass="dtstart"title="2007-05-01">The first of May, 2007</abbr>. <abbrclass="dtstart"title="2007-05-01">2007-05-01</abbr>. <abbrclass="dtstart"title="2007-05-01">Tuesday, 1 May 2007</abbr><abbrclass="dtstart"title="2007-05-01">2007, day 121</abbr><abbrclass="dtstart"title="2007-05-01">May Day, 2007</abbr><abbrclass="dtstart"title="2007-05-01"lang="FR">1er mai, 2007</abbr><abbrclass="dtstart"title="2007-05-01"lang="ES">1 de mayo, 2007</abbr>and the following may be used in, say, a list, table, or page, headed "2007":
<abbrclass="dtstart"title="2007-05-01">1 May</abbr>Better (with HTML5 time element)
<timeclass="dtstart">2007-05-01</time><timeclass="dtstart"datetime="2007-05-01">1 May 2007</time><timeclass="dtstart"datetime="2007-05-01">1st May 2007</time>. <timeclass="dtstart"datetime="2007-05-01">May 1st 2007</time>. <timeclass="dtstart"datetime="2007-05-01">The first of May, 2007</time>. <timeclass="dtstart"datetime="2007-05-01">2007-05-01</time>. <timeclass="dtstart"datetime="2007-05-01">Tuesday, 1 May 2007</time><timeclass="dtstart"datetime="2007-05-01">2007, day 121</time><timeclass="dtstart"datetime="2007-05-01">May Day, 2007</time><timeclass="dtstart"datetime="2007-05-01"lang="FR">1er mai, 2007</time><timeclass="dtstart"datetime="2007-05-01"lang="ES">1 de mayo, 2007</time><timeclass="dtstart"datetime="2007-05-01">1 May</time>anti-patterns
These are all past examples that are usages to avoid.
Authors MUST NOT use the abbr element as shown in these examples, as either the element text or the title attribute text are not easily human readable.
<spanclass="dtstart">20070501</span><abbrclass="dtstart"title="20070501">1 May 2007</abbr><abbrclass="dtstart"title="20070501">1st May 2007</abbr>. <abbrclass="dtstart"title="20070501">May 1st 2007</abbr>. <abbrclass="dtstart"title="20070501">The first of May, 2007</abbr>. <abbrclass="dtstart"title="20070501">2007-05-01</abbr>. <abbrclass="dtstart"title="20070501">Tuesday, 1 May 2007</abbr><abbrclass="dtstart"title="20070501">2007, day 121</abbr><abbrclass="dtstart"title="20070501">May Day, 2007</abbr><abbrclass="dtstart"title="20070501"lang="FR">1er mai, 2007</abbr><abbrclass="dtstart"title="20070501"lang="ES">1 de mayo, 2007</abbr><abbrclass="dtstart"title="20070501">1 May</abbr>The lack of dashes in "20070501" makes it read like a large number, not a date, both when viewing it, and when listening to it being read by a screenreader.
Discussion
about datetimes
Avoid using the abbr-design-pattern for datetimes.
E.g. Authors MUST avoid doing this:
<abbrclass="dtstart"title="20051012T11:10-0100">10 past 11 o'clock on the 12th</abbr>Ideally use the HTML5 time element:
<timeclass="dtstart"datetime="2005-10-12T11:10-0100">10 past 11 o'clock on the 12th</time>Note the use of the hyphenated date to make it more human readable, as the more readable that even machine data is made, the greater the chance that a human will be able to accurately check it and verify that it matches the locale/language-specific contents of the time element.
Alternatively, if the microformats tools you're using don't support HTML5 (yet), you may use the value-class-pattern with the abbr-design-pattern:
<spanclass="dtstart"><abbrclass="value"title="11:10">10 past 11 o'clock</abbr> on <abbrclass="value"title="2005-10-10">the 10th</abbr></span>informal names
Using ABBR to encode more formal human data around something less formal:
<abbrclass="author"title="Danny Ayers">Danny</abbr>This use is discouraged under the Don't Repeat Yourself principle, as it is a case of *more* information being less visibly present, namely, the family name in this case. If someone is not willing to make some information visible, then we shouldn't be encouraging them to store that information invisibly or less visibly, for all the same reasons that invisible metadata is bad/futile in the first place."
screen readers
The title attribute of the <abbr> tag MUST always be human readable and speakable.
Screenreaders such as JAWS and others which use title attributes from abbr, and when used properly (as in this example below from the WCAG group), pronounce words which would otherwise be unreadable or confusing.
<p>Sugar is commonly sold in 5 <abbrtitle="pound">lb.</abbr> bags.</p><p>Welcome to the <abbrtitle="World Wide Web">WWW</abbr>!</p>If screen readers are unable to turn title content into something comprehensible, this will lead to accessibility failures. Here is a bad example:
we're having a party on <abbrclass="dtstart"title="20070312T1700-06"> March 12, 2007 at 5 PM </abbr>would be read by Jaws as
we're having a party on Twenty million seventy-thousand three-hundred twelve tee seventeen-hundred dash zero six.
The accessibility task force from webstandards.org recommended:
<spanclass="dtstart"title="20070312T1700-06"> March 12, 2007 at 5 PM, Central Standard Time </span>or
<spanclass="dtstart"> March 12, 2007 at 5 PM, Central Standard Time <spanclass="value"title="20070312T1700-06"></span></span>But both these approaches are problematic due to the title attribute being not easily human readable/verifiable because of:
- unhyphenated date, e.g. bad: 20070312; good:2007-03-12
- uncoloned time, e.g. bad: 1700; good: 17:00
- timezone offset without minutes, e.g. bad: -06; better: -0600
- combining date, time, and timezone into a single string without human-friendly separators
However, based on this input and subsequent research into better alternatives, the microformats community developed the value-class-pattern with the following two alternatives:
<spanclass="dtstart"><abbrclass="value"title="2007-03-12">March 12, 2007</abbr> at <abbrclass="value"title="17:00">5 PM</abbr>, <abbrclass="value"title="-0600">Central Standard Time</abbr></span>or
<spanclass="dtstart"><spanclass="value-title"title="2007-03-12T17:00-0600"></span> March 12, 2007 at 5 PM, Central Standard Time </span>And again, the even better alternative is to use the HTML5 time element:
<timeclass="dtstart"datetime="2007-03-12 17:00-0600"> March 12, 2007 at 5 PM, Central Standard Time </time>