The draft W3C style guide

About this document

This section is a place for notes about this document itself. It is meant to be removed before publication.

(@1) Current status

This document is in development. It probably contains sections that are controversial and choices that should go the other way. It has only been discussed in the Web-design Task Force, not with the team yet.

Sentences that are known to require changes or at least discussion are marked up with class=issue (which shows a red flag in the margin if CSS is turned on).

(@2) Location

This is a draft of a new style guide for the W3C websites. Once we are proud of it, it will be public and its URL will be what? /Style/StyleGuide? /Consortium/StyleGuide? /Press/Style?…

(@3) Sources

Links to older style guides, guidelines, issues, etc.:

(@4) More material

This page is probably not complete. There are various ideas elswehere not yet moved to this document.

(@5) Feedback

Comments are best sent to <team-webdesign-tf@w3.org>

Summary

This is [a draft of] the general style guide for the W3C websites and for W3C's communication in general. It contains guidelines for the style (colors, fonts, layout, graphical elements), content (language, grammar, spelling, writing style, required information), metadata (markup, links), and maintenance (documentation, validation, automation, dynamic pages) for all pages, services and other publications.

W3C's communications adhere to general principles expressed in the W3C Mission and in the ethical web principles (a superset of the mission, formulated by the TAG in 2019). [Do we officially adopt those ethical principles?]

Some special types of pages cannot apply all guidelines (e.g., pages on GitHub or other servers we don't control) and some pages have additional rules and guidelines (e.g., Technical Reports follow the pubrules).

Table of contents

The essentials

[Manuscript illumination: a writer at his desk]

An illumination from Le Roman de la Rose (14th century manuscript). Source: Wikipedia

If you don't have time to make a page follow all the guidelines, then at least apply the ones below. They ensure the page is recognizable as a W3C page.

(A2) Signed

Pages should be signed by a person and have an e-mail address for feedback. Pages of which the main content is generated should say so, but still have an e-mail address for feedback. (See ‘Examples of signed pages’ for suggested markup.)

(A3) Accessibility

Accessibility level AAA for the most important pages (the most popular), at least A for other pages. (See ‘WCAG 2.1 at a Glance’ for a summary of content accessibility guidelines and ‘How to Meet WCAG 2’ for the details.)

[Verify with WAI experts.]

(A4) Old styles for old pages

Don't change old pages just to update the style, even if their style is different from these guidelines. That needlessly changes the last-modified date. But if there is new content, i.e., more than a fix for a spelling error or a broken link, then the style should be updated as well.

Indeed, it is a good thing if old pages look old. And this style guide changes every few years, in part to ensure that pages look their age.

However, it is the intention that the guidelines in this particular section, the essentials, will remain unchanged for a long time. That way, pages visually belong to an age and, at the same time, always look like W3C pages.

Spelling

[Print: some black and red Hebrew letters, digits, lines and circles arranged in four crossing diagonal lines]

El Lissitzky (1890–1941): Design (1922). Source: Wikipedia

This section contains rules and guidelines about spelling, grammar and writing style.

(B1) No spelling, grammar or markup errors

No document that is visible to the public or the members should contain any spelling, grammar or markup errors, unless the error is on purpose or the text is clearly marked as not having been written by W3C staff. We want to show we are capable of quality, even in details and even in pages that have temporary content and are expected to be updated soon.

After writing a page, take a break (as long a break as possible) and then carefully reread what you wrote. Always use a spell checker and a validator. If possible, ask a colleague to copy-edit the page. (See also ‘content review’.)

To validate the markup, you can use the online markup validator (also available as a comma tool on our main site: add ‘,validate’ after the URL) or a local validating parser:

If you wrote any CSS, validate that, too, with the CSS validation service.

[Can we restart the weekly service that reported to <w3t@w3.org> the 25 invalid pages on our site that were most popular during that week?]

(B2) American English

The language of the W3C website is American English (except for pages that are translated, of course). The dictionary of reference is Merriam-Webster's Collegiate® Dictionary, 10th Edition or newer. E.g., W3C writes ‘color’ rather than ‘colour’ and ‘standardize’ rather than ‘standardise’.

(B3) Quote marks

The recommended quote marks in English text are the left and right single quotes: ‘’. They are sufficient to quote a word and don't take up much space. Nested quotes get left and right double quotes: “”. If those are too difficult to type, you can use ASCII straight double quotes at the first level ("") and ASCII apostrophes at the second (''). Or use the SGML/XML character entities: &#8216;&#8217; (‘’) and &#8220;&#8221; (“”).

(B4) Punctuation around quote marks

When punctuation (comma, period, semicolon, colon, question mark, exclamation mark) follows a word or a phrase in quotes, the punctuation is put after the closing quote:

A meeting, also called a ‘ftf’, may be held.

Are all documents ‘resources’?

But when the quoted phrase itself ends with an exclamation mark (!) or question mark (?), that exclamation mark or question mark is inside the quotes:

A company called ‘Yahoo!’ was one of them.

That piece was called ‘Why?’.

If a complete sentence that originally ended with a period is quoted, it loses its period:

The last sentence, ‘The focus is on privacy’, was underlined.

Didn't it say ‘This is a draft’?

The exception is if a sentence that ends with a period is quoted at the end of a sentence that would also end with a period. Then the period inside the quotes is kept and it is the one after the quotes that is omitted:

The last sentence is: ‘The focus is on privacy.’

[The last two rules are hard to read. Need a rewrite.]

(B5) Lowercase headings

Do not Capitalize Every Word In A Heading, as you find in American newspapers. Making the text bold or a little bigger is enough to make it stand out. Without the capitals, the text is easier to read, especially for people not used to American newspapers. (The tradition to capitalize words dates from the days when newspapers were set with lead type and printers didn't have a lot of different sizes. The use of capitals made the text look a bit bigger.)

Also do not write headings in all-caps. ALL-CAPS MAKES THE TEXT SLOWER TO READ, AS YOU CAN SEE HERE. And it is especially difficult for people with reading difficulties or low vision.

(B6) Capitalized words

Here is a list of words to write with an initial capital letter:

Here is a list of words to write, in general, without an initial capital letter:

(B7) Names of W3C technologies

Write acronyms and abbreviations of W3C technologies as they are written in the corresponding specifications (e.g., ‘SMIL’, ‘WebRTC’ and ‘HTML’, not ‘S.M.I.L.’, ‘Web-RTC’ and ‘H.T.M.L.’)

(B8) Acronyms and abbreviations

Unless they are very well-known (e.g., because they are in everyday English, such as ‘e.g.’ or ‘viz.’), abbreviations and acronyms should be marked up with an abbr element that contains the expansion, at least the first time they appear on a page. If possible, there should also be a hyperlink to a page describing the meaning. E.g.:

<a href="https://en.wikipedia.org/wiki/Transmission_Control_Protocol" ><abbr title="Transmission Control Protocol" >TCP</abbr></a>

(B9) Reader vs user

To refer to the people or agents reading our pages, use either ‘user’ or ‘reader’, but if there is any possibilty of confusion with other kinds of users (e.g., ‘users of HTML’, who aren't readers, but authors; or ‘users of CSS’, who aren't readers either, but designers), then use ‘reader’.

(B10) Cell vs mobile

Prefer ‘mobile phone’ over ‘cell phone’ (even though the latter is American English and the former British English), because our related activities are known as the ‘Mobile Web Initiative’, ‘Mobile Web best Practices’, ‘Mobile Accessibility‘, etc.

(B11) ‘a’ vs ‘an’

Use ‘a’ before an abbreviation if the pronunciation starts with a consonant. Use ‘an’ if it starts with a vowel: an HTML page (aitch-tee-em-el), an XML document (ex-em-el), a W3C workshop (double-you-three-see), a CSS rule (see-es-es), a REC (rec), an SVG graphic (es-vee-gee), a WG (double-you-gee), an IG (aye-gee), an AC meeting (ai-see), a TPAC registration (tee-pack).

(B12) Plural s

Plurals of abbreviations and acronyms get an ‘s’ without an apostrophe: RECs, TPACs.

(B13) Forms

The first word (and only the first word) on a button is capitalized:

Similarly, the first word in the label of a checkbox is capitalized:

(B14) Collective nouns

Collective nouns are words that refer to a group of people, but grammatically they are singular:

W3C publishes… (not: publish)

The working group meets… (not: meet)

The audience was… (not: were)

Look at IBM. It wants… (not: they)

(B15) E-words

The prefix ‘e’ (for ‘electronic’) is often attached to nouns to indicate the digital equivalent or the digital part of something: ebook, e-commerce, email, e-reputation, e-wallet….

Use e-words if they are common, otherwise use a description. They are all written with a hyphen, except email and ebook, which we prefer without. In particular:

E-word Use instead:
e-book ebook (preferred)
e-business online business
e-commerce -
e-government -
e-learning -
e-mail email (preferred)
e-marketing online advertising
e-reputation online reputation, reputation
e-tailer online shop
e-wallet digital wallet
e-zine online magazine

(B16) Cyberwords

A similar prefix to ‘e-’ is ‘cyber’: cybercrime, cyberattack, cybercafé, cyperspace, etc. It is always written without a hyphen.

As of 2018, many technical people see ‘cyber’ as a word used by politicians, where an engineer would rather put ‘online’, ‘digital’, ‘Internet’, ‘network’, ‘web’ or some such. So be careful who your audience is: ‘Cyber’ is useful when talking to policy makers, but better avoided when talking to programmers.

(B17) Em dash and en dash

A long dash can be used as an alternative for a comma or parenthesis. The Dutch name for it – gedachtenstreepje, literally ‘thought dash’ – is evocative of its function.

The tradition in American English is to use the em dash (‘—’ or &mdash;) with no spaces around it—like this.

However, I (Bert) think this looks ugly. It connects words that do not normally form a compound. So I suggest we use in this case the British custom of using the shorter en dash instead (‘–’ or &ndash;), which is used with spaces – like this. In fact, Robert Bringhurst (in The elements of typographical style, version 2.5, 2002) agrees with me.

(B18) En dash for ranges

The en dash is also used, in both traditions, to indicate a range of numbers, times or dates, in this case without spaces. E.g.: 14 August–5 September, levels 7–10, 14:00–14:30.

If for some reason it is too difficult to type an en dash, use an ASCII hyphen-minus (-).

(B19) Ellipsis

An ellipsis (…) normally indicates that something is omitted, but can also be used as a short pause, when a comma, semicolon, en dash, period or paragraph break is not enough.

If you are sure the text will be rendered in a monospace font, use three dots with no spaces in between (like this...), otherwise use an ellipsis character (‘…’ or &hellip;).

This differs from what The Chicago Manual of Style recommends. It makes an ellipsis out of three periods with spaces before, after and in between ( . . . ). But, with Bringhurst (cited above), we think that makes the ellipsis much wider than needed. The ellipsis character, in most fonts, has tighter spacing, while still being clearly visible. It is used with no space before it and one space after it, except at the start of a sentence, where it has a space before and no space after. (Mathematics has its own rules, but usually there is no space on either side.)

When the ellipsis indicates that something is omitted, it should not be preceded by ‘for example’ and not be followed by ‘etc.’, because that would be redundant:

Use any element: A, EM, VAR…
Use any element, e.g., A, EM or VAR.
Use any element: A, EM, VAR, etc.

When omitting something from a quotation, enclose the ellipsis in square brackets. E.g.:

In her book on the ellipsis […] Anne Toner suggests that the first use of the punctuation in the English language dates to […] 1588. – Wikipedia

If an ellipsis occurs at the end of a sentence, omit the period that would normally end the sentence.

(B20) Compound modifier

When an adverb or a noun precedes an adjective in a noun phrase, check carefully if the two shouldn't be connected with a hyphen to make the meaning clear. Some examples (stolen from Wikipedia):

  1. ‘Man-eating shark’ (as opposed to ‘man eating shark’, which could be interpreted as a man eating the meat of a shark)
  2. ‘Wild-goose chase’ (as opposed to ‘wild goose chase’, which could be interpreted as a goose chase that is out of control)
  3. ‘Long-term contract’ (as opposed to ‘long term contract’, which could be interpreted as a long contract about a term)
  4. ‘Zero-liability protection’ (as opposed to ‘zero liability protection’, which could be interpreted as there being no liability protection)

(B21) He/she

[This section needs more input. There are people who claim the second example below sounds correct to their ears and some even say the first sounds incorrect. Make a different recommendation? Make no recommendation?]

[There are people who want to be referred to neither as a man nor as a woman. At this point in time that seems to be rare enough that we don't need any rules.]

When you rewrite a sentence because you want to avoid the words ‘he’, ‘him’ and ‘his’, make sure the result is grammatical. E.g.:

‘Each user creates his own profile.’ (Correct.)

* ‘Each user creates their own profile.’ (Incorrect, user is singular.)

* ‘Each user creates her own profile.’ (Incorrect, you don't know if the user is female.)

‘All users create their own profile.’ (Correct, use plural throughout.)

‘Each user creates an individual profile.’ (Correct, avoids pronouns.)

When inventing personas to explain a process and their gender is not important, it is good style to alternate male and female names. E.g., cryptographers traditionally use Alice (the sender of a message), Bob (the receiver) and Eve (the evil party or the eavesdropper).

(B22) Smileys

Avoid smileys and other emoticons on web pages. Restrict their use to informal written conversations only. If you do use one on a web page, use the corresponding Unicode character, not the ASCII transcription:

ASCII Character HTML
:-) &#x263A;
:-( &#x2639;
;-) 😉 &#x1F609;
:-\ 😕 &#x1F615;
:-O 😃 &#x1F603;

(B23) Numbers

Numbers up to twelve inside a sentence are normally written with letters: ‘I wrote three pages in two hours.’ Larger numbers use digits: ‘There are more than 2000 lines.’ If a sentence has both large and small numbers, use digits for all: ‘There are 2 rooms for 80 people each.’ Avoid to start a sentence with digits. Rewrite the sentence or use letters instead.

Numbers with units are always written with digits: 2 km, 9%, 5 GB.

The thousands separator in English is the comma. It can be omitted for numbers below 10,000, especially if there are no higher numbers in the same text. But it is recommended for other numbers: 2000 or 2,000, 7500 or 7,500, 17,500, 1,000,000, 375,300.

Years and page numbers are always written without a thousands separator: the year 2018, on page 1073.

(B24) Numbers with units

Try to put a ‘narrow no-break space’ (&#x202F;) between a number and its unit. It is easier to read 50 m than 50m and 50 m is too wide. If you can't type the narrow space, use at least a ‘no-break space’ (&nbsp;), to avoid a line break after the number.

However, when writing about CSS it is probably better to omit the space, because that is how dimensions are written in a style sheet: 5px, 3.7em

There is no space before percent signs: 25%, 100%

Currency symbols come before the number, without a space: $20, ¥4500. (If you are using ambiguous signs, such as $, make sure the context makes it clear which country is meant, or make it explicit: US$20.) When using the currency abbreviation instead of the symbol, there should be a no-break space between it and the number: USD 20, EUR 5.50.

Units do not get a period nor a plural ‘s’: a 5 MB. file, the file is 5 MBs.

(B25) kB, kb, MB, MiB…

Lowercase b is for bit, uppercase B is for byte (eight bits). The prefixes k, M, G, etc. stand for kilo, mega, giga, etc. (see the table below) and represent 1,000, 1,000,000, 1,000,000,000, etc.

When followed by a lowercase i, they represent powers of 1,024 instead: 1,024, 1,048,576, 1,073,741,824, etc.

Decimal Binary
Symbol Name Value Symbol Name Value
kB kilobyte 1000 kiB kibibyte 1024
MB megabyte 10002 MiB mebibyte 10242
GB gigabyte 10003 GiB gibibyte 10243
TB terabyte 10004 TiB tebibyte 10244
PB petabyte 10005 PiB pebibyte 10245

Note that there are no dots: not ‘5 G.B.’ but ‘5 GB’.

(B26) Electronic addresses

To make email addresses and URLs easier to copy, avoid putting a comma or period after them. Rewrite the sentence or enclose the address in angle brackets: <webmaster@w3.org>.

(B27) Pixels

A pixel (from ‘picture element’) is the smallest dot a bitmap screen can show. But there are screens now that can show very small dots, sometimes more than 300 per inch. So in many cases, when people talk about a pixel, they mean in fact the CSS pixel (called ‘px’), which corresponds to a visual angle: the effect on the eye of a dot of 1/96th of an inch (about 0.26 mm) on a desktop computer screen viewed from a normal viewing distance. (Which is how a pixel looked on an average monitor in the 1990's.)

When HTML refers to a size in pixels, it means the size in px. (For example in images: <img src=... width=350> indicates the image is meant to be 350 px wide.) When a browser displays a raster image (such as JPEG or PNG), it maps one image pixel to one px, even if that means it occupies in reality four, nine or even more actual pixels on the screen.

So, when talking about pixels, check if there is possibility of confusion and, if so, clarify whether you are talking about hardware pixels or the visual size.

(B28) That vs which

In American English, the relative pronoun ‘that’ is used to identify an object:

The cable that is on my desk is too short

(There are several cables, but this sentence only talks about the cable on the desk.) The relative pronoun ‘which’ is used to give information that is not essential for identification:

The cable, which is on my desk, is too short.

(You can omit the ‘which’ phrase and it is still clear which cable is meant.)

There is a comma before ‘which’, but not before ‘that'.

In British English, you can use ‘that’ instead of ‘which’ and it is the comma that determines whether the phrase identifies something or can be omitted: ‘The cable, that is on my desk, is too short.’

To avoid confusion for people used to American English, it is recommended to use the American convention.

(B29) Citing titles

Put the title of a ‘larger’ work (a book, a film, a journal, a work of art, etc.) in italics. Put the title of a smaller work (an article, a chapter, a report, etc.) in quote marks:

He played in Hamlet.

See the section ‘Type Field’ in ‘Tags for Identifying Languages’.

Did you see the elephant in Gone with the wind?

Note that the full stop (.) after ‘Hamlet’ and the question mark (?) after ‘wind’ are included in the italics, even though they are not part of the title. See ‘Punctuation after bold or italic words’.

(B30) Punctuation after bold or italic words

If a word is followed by punctuation and you know the word will be in bold or italics, then include the punctuation in that style, unless that leads to ambiguities (e.g., in a code example):

Do you call that green?

It is actually made from wood: cherry wood.

Did you type cvs up Overview.html?

Otherwise there may be too much space before the punctuation.

(B31) It's, he's, doesn't, can't, we've…

Contractions of ‘is' and ‘has’ to ‘'s’, and of ‘not’ to ‘n't’, generally sound less formal, closer to spoken text.

Most of our web pages should use the long form: ‘it is’, ‘it has’, ‘he is’, ‘he has’, ‘does not’, ‘cannot’, ‘we have’, etc.

(B32) Phone numbers

Always start with a + and a country code (unless it is a number that cannot be dialed from another country). Put spaces between groups of digits. Try to group the digits in the way most common for the country from which the number comes.

In the US, it is common to group digits 3+3+4: +1 617 555 5555 (+ for accessing an international line, 1 for the USA, 617 for Cambridge MA, 555 5555 for the local number).

In France, it is common to group digits in pairs: +33 5 55 55 55 55 (+ to get an international line, 33 for France,  5 55 55 55 55 for the local number). Note that somebody in France could dial this number as 05 55 55 55 55, but the international form works everywhere, including in France.

(B33) Periods inside and outside parentheses

When a whole sentence is inside parentheses, the final period is also inside the parentheses:

It is available from the Web. (At least it was yesterday.)

We use Noto Sans. (Sans means sans-serif.)

But when only part of the sentence is in parentheses, the final period is outside:

The preferred color is #EEE (a very light gray).

You can click on it (unless it is hidden).

(B34) Punctuation in lists

If a bulleted or numbered list has (some) items that are whole sentences, or even several sentences, then each list item starts with a capital letter and ends with a period. For example:

The blue process has three steps:

  1. Take the item and inspect it.
  2. Inspect it again. Maybe inspect it a third time.
  3. Leave it overnight.

If the list has only short items, not whole sentences, each item starts with a capital letter and has nothing at the end, neither a period nor a comma:

The choices are:

  • Margherita
  • Pepperoni
  • Daily special

If such a list might be displayed inline as well in some cases (‘The choices are: margherita, pepperoni and daily special.’) due to a device-dependent style sheet, some compromise, or some clever style rules, may be needed.

(B35) Chicago manual of style

[We are still looking for a good resource that is available online without a paid subscription.]

Except where this style guide says otherwise, apply the recommendations of a recent Chicago manual of style (say the 13th edition or later).

(B36) Other style guides

The conventions for writing Linux man pages include a style guide, which also has useful rules to follow. The link in the previous sentence goes to an online copy on the Debian site. You can also type man 7 man-pages on any Linux computer.

The European Union's style guide describes the structure of various publications, language-independent conventions for writing country names, addresses, telephone numbers, etc. and rules for writing in English.

Wikipedia's (English) Manual of Style also has many style rules that are generally useful.

Interaction with human readers and automated agents

[Painting of a young girl reading]

Jean-Honoré Fragonard (1732–1806): The reader (1770). Source: Wikipedia

This section contains rules and guidelines about metadata (all the elements, attributes and protocol headers that inform a reader about the type, provenance and history of a page) and about making pages faster to load, parse and read.

(C1) Mobile

The most important pages should work well on mobile and on devices with cumbersome interaction (smart TVs), other pages should at least be functional.

This characteristic of pages is known under many names: device-independence, fluid design, responsive design, adaptive design and mobile-first. It involves layout that adapts to different screen sizes (either by not setting large, fixed sizes or by providing multiple styles), and interaction that does not rely on particular input mechanisms (a mouse, a keyboard).

For more info on making pages or web applications mobile-friendly, see the summary of Mobile Web Best Practices or the draft of a W3C Note on Mobile Accessibility. The quickest way to learn how to make a page device-independent used to be to run the W3C Mobile Checker on it, but as of June 2019 the checker is not running. An alternative, of course, is to find a smartphone and a smart TV and just try it out…

[Are there other good how-to guides?]

(C2) Print

Make sure pages print reasonably well. It is more important for some pages (meeting agendas…) than others. But all pages may get printed some day by somebody leaving on a trip.

If you use one of the style sheets under /StyleSheets/, the author of the style should have taken care of it. (If your page doesn't print well, and the style sheet's documentation doesn't explain what to do either, file a bug report with the Comm team.) If you write your own style sheet, make sure that the page prints well with it, or add special style rules for print.

[Need to find (or write) a small tutorial on how to link to a print style sheet or add rules for print to an existing style sheet. There is a good resource in French, ‘Faire une feuille de style CSS print pour l'impression’. Is there something similar in English?]

The ‘,pdf’ comma tool may be useful: It returns a PDF version of the page.

(C3) Screenscraping

Among W3C's goals are a Web that works in browsers and other user agents and a Web that is semantic. And, of course, W3C's own websites should be the best possible examples.

Another way to say that is that W3C's websites should make ‘screenscraping’ easy. (‘Screenscraping’ is the process of extraction of information from a page by a computer, e.g., by a web spider or a virtual assistant, that precisely does not involve rendering the page on a screen and does not require human eyes. I.e., it relies solely on interpreting the text and the markup. The name comes from the days when data produced by some old (financial) applications was only easily available in the form of screendumps from text terminals. Other terms are data scraping and Web scraping.)

A consequence of the screenscraping goal is that using embedded scripts to put content in a document (‘AJAX’) is not allowed, because links in JavaScript are very difficult to find (the ‘halting problem‘). See ‘JavaScript’ for more on embedding scripts.

If a document contains data that originally comes from a database or a non-HTML file (e.g., a file in XML, JSON, CSV or RDF), then convert the data to HTML on the server side.

(C4) Section removed

[The content of this section was moved elsewhere. The heading will be removed later.]

(C5) Raw data

On the other hand, if you have the main content of an HTML document available in an easy-to-parse format (such as XML, JSON or CSV), do put a link to that data in the document, and give it a rel=alternate attribute. Anybody planning to write a screenscraper can then extract the data from the other format instead, with less programming.

Make sure the alternative format does indeed have the same data. The best is to have an automatic process that ensures it.

(C6) Microformats

It is recommended to use microformats for events, addresses and other things for which microformats exists. That helps screenscraping, because there is already software to extract those. [Or is there more software for RDF/a?]

(C7) rel=canonical

Pages that have multiple URLs, or pages that have essentially the same content as other pages (print version, mobile version, single-page version vs multi-page version, PDF version, etc.) should have a link to the URL that is considered the ‘canonical’ version. The canonical version is the one whose content includes the content of all the other pages (see RFC 6596). Search engines may index that canonical page in preference to the other pages, or list it before the other pages.

The link to the canonical page should be a link in the head part if it is an HTML document:

<link rel=canonical href="URL-of-canonical-document">

If the document is not HTML, but is served over HTTP, the link should be in the HTTP headers:

Link: <URL-of-canonical-document>; rel="canonical"

Exception: As of July 2018, the pubrules still requires the opposite for Technical Reports. The link with rel=canonical does not point to a document that has the same content, but to a document that has potentially newer content. (The idea is that this makes the latest versions appear higher in search result, although with the risk of making text from old drafts impossible to find.)

(C9) Photo of the author

It is recommended that the signature contains a photo of the author, unless the page is mainly generated. This helps give W3C a more friendly face and distinguishes us from standards organizations whose public face is an anonymous secretariat.

[Any idea for making generated pages more friendly as well?.]

[Check these sizes.] The preferred size for such a photo is 150×200 pixels (3:4 aspect ratio), and it should be scaled to a width of 4 times the default font size (in CSS: ‘width: 4rem’).

See ‘Examples of signed pages’ for suggested markup.

(C10) Last-modified date

Pages should say when they were last changed and that date should correspond closely to the HTTP Last-Modified header.

How closely depends on how often the page changes. For a page that changes less than once a day on average, it is probably enough if the dates are the same; the hours may be different or omitted.

An acceptable way is to include one of the CVS keywords $Date$ (as in the signature of this guide) or $Id$. They produce, respectively, something like

$Date: 2022/08/15 21:08:19 $

$Id: DraftStyleGuide.html,v 1.45 2019/06/07 01:46:00 bbos Exp $

But note that these keywords are only correctly expanded in HTML pages that are maintained in CVS. Not in pages written in PHP, in a wiki, in WordPress, in PlanetPlanet or otherwise generated by a CGI program; nor in pages that are redirected to GitHub or other external servers.

Wikis, WordPress and PlanetPlanet include dates automatically. In PHP, consider using the function date(). The best technique for other pages will differ.

See also ‘unambiguous dates and times’.

(C11) Creation date

It is recommended that pages also say when they were first created.

(C13) Privacy policy

The bottom of a page should also have a link to our privacy policy, which goes to https://www.w3.org/Consortium/Legal/privacy-statement-20140324. See ‘Examples of signed pages’ for suggested markup.

[Check with legal if it is better to have ‘usage policies apply’ and a link to https://www.w3.org/Consortium/Legal/ipr-notice, as some pages on our site have currently.]

(C14) Internationalization

The recommended character encoding for text documents (including HTML) is UTF-8. But whatever encoding is used, it should be declared explicitly in the document. Use either a meta element like this (valid in all versions of HTML):

<meta content="text/html; charset=utf-8" http-equiv="Content-Type">

or like this (HTML5 only):

<meta charset="utf-8">

HTML documents must have a lang attribute on the html element, and on any element that has a different language.

<html lang="en-us">

(‘en-us’ means American English; use a different language as appropriate.) Hint: Use the i18n checker to find (potential) problems on a page. The checker is at

https://validator.w3.org/i18n-checker/check

but the easiest way to call the checker is to append ‘,i18n’ to the URL of the document to check, e.g.:

https://www.w3.org/,i18n

(C15) Image sizes

Although you can use CSS to scale a raster image in an HTML page to any size you like, it is recommended to scale images down to (approximately) the right size before putting them in a web page. That avoids that a user has to wait for a megabyte of image to download, when the image is only going to be displayed at a size of a few hundred pixels.

If the image may be displayed at different sizes, including large ones, and the page is in HTML5, you can use HTML5's picture element to provide two or more different sizes of the image, so that the larger ones only have to be downloaded when needed. E.g.:

<picture>
 <source media="(min-width: 45em)" srcset="large.jpg">
 <source media="(min-width: 32em)" srcset="med.jpg">
 <img src="small.jpg" alt="The wolf runs through the snow.">
</picture>

(C16) Headings and subheadings

Use plenty of headers (h2 and h3), make them short, descriptive and use the actual key words from the text (i.e, not a metaphor you will only understand after you read the section).

(C17) Shallow structure

Don't nest sections too deeply. There is no need to group sections under a common heading if their relation is clear enough without. Too many levels may confuse readers rather than help them.

A rule of thumb is to use a single h1 for the page title (see title and h1 below), and h2 & h3 for sections & subsections. If you find yourself needing an h4, check carefully if one of the levels above isn't redundant, if the h4 itself shouldn't be replaced simply by a bit of vertical space, or if the fourth level isn't in fact a list (ol, ul, dl).

(C18) Title

Make the page title context-independent as much as possible. Somebody who finds the title in a search engine or in a list of bookmarks among unrelated pages should be able to make a good guess as to what the page is about.

(C19) Title and h1

Use a single h1 element that is the same or similar to the title element (because not all browsers make it easy to see the title).

(C20) Speed

Hypertext is text with links that you can resolve almost instantaneously. It should not take longer than three seconds. If it takes longer, it feels like an old-fashioned book. You can follow the links in a book, but not quickly: you need to go to your bookcase, to a library, to an book shop…

Of course, the network conditions and the user's computer have some influence on the speed with which a link is resolved, but do try to keep documents small (no redundant markup), with small style sheets and small images.

Speed can also suffer if the server has to do a lot of work, in particular if it has to generate the document on the fly (e.g., with PHP). If the document isn't very dynamic, e.g., if it doesn't change more than once a day, consider generating a static document once a day by means of a cron job or similar.

There are cases where the user doesn't mind waiting. If you offer a link to get, e.g., ‘all data in one file’ and warn that it is a few megabytes long, the user can balance the convenience of having all data in one file against having to wait.

(C23) Masthead

The ‘masthead’ of a page is the area above the main content, where you typically find the logo of the site. In our case, the masthead contains at least the W3C logo and should contain a navigation menu and a search box, The title of the page (an h1 with roughly the same content as the title element) can be inside the masthead, or just below it. A link to a list of translations or to an Atom/RSS feed can also be inside the masthead.

The masthead should be small: four lines maximum. It provides context for users (hence the W3C logo and the page title), but users shouldn't need to scroll to see what they came for. Or at least to see whether the page contains what they came for.

(C24) Date and time

When writing about something that has a date and a time (‘we will publish tomorrow’, ‘the group met last week’, ‘the deadline is August 15’), consider when the next time is that you update the text. And also how likely it is that you don't update it then. In other words, if people read the page next week, next month, next year or in ten years, will the text still make sense?

If in doubt, write the text differently and include the year.

This doesn't hold for a blog post. It normally has a date at the top and people expect blog posts to be outdated.

(C25) Unambiguous dates and times

Always write the date or time in an unambiguous way for an international audience. Is 9/11 in November or in September? Is 6 o'clock in the morning or in the evening? And in what time zone? Use ISO dates (2001-09-11) or include the month in letters (September 11), the latter is preferred. Use a 24-hour clock with leading zeros (06:00 or 18:00) or add AM/PM (6 AM, 6 PM), and add a city name or time zone name (Paris, CET, Boston, EST) when the time zone isn't clear. City names are best: People who don't live in Boston do know Boston, but not necessarily that its time zone is called EST.

[The date command on GNU/Linux generates AM/PM (uppercase, no dots) for the en_US locale. As that command is likely to be used when generating pages, shall we recommend that spelling, or rather a.m./p.m., as some style guides prefer? (The date command on MacOS generates 24-hour times for the en_US locale.)]

(C28) Do not open new windows

Do not use the target="_blank" attribute on a elements to open a new window when a user clicks a link. It makes it impossible for the user to use the Back button to return to the previous page. Indeed, the user may not notice what happens (because the new window overlays the previous one, or the action only created a new tab), and become confused why the Back button doesn't work.

(C29) Required form fields

Mark form fields that must be filled with an asterisk, if possible a red asterisk. Explain the asterisk at the top: ‘* indicates required fields.’

(C30) No automatic customization/personalization

The content of a page at a given URL should depend only on the URL, on the user's preferred language expressed via the Accept-Language header in HTTP, the user's preferred data format via the Accept header, and on the time, because many pages change over time. Of course, this applies only to successful requests (when the server returns a 200 status code). If there is no content at the URL, the user isn't authorized to get the content or some other error occurs, the returned content, if any, should rather describe the error.

However, the result of submitting a form that uses the POST method (rather than the GET method) may, and probably does, differ, depending on what the user filled in the form. We may assume users know this.

E.g., if you bookmark a page and come back to it later, you get the same content, unless the page has been updated in the mean time. Or if you get a URL from somebody else, you should see the same content as that somebody. And if you use two browsers, or other HTTP clients (such as wget or curl), all of them should get the same content, as long as you configured them to ask for the same languages and data formats.

Any adaptation to the environment (such as the window size) should be done through the style, or, if there is no other way, through JavaScript, but such that saving the page locally always saves the same content, no matter if you used a client with a big window, a small window, or no window at all.

E.g., it is not acceptable (as some wikis do), to return a 200 status and a page with a password form when the client isn't authorized to see a page at a given URL. If the server isn't able to send the proper content of the page, it should reply with an error (e.g., a 401 or 403 status code). Because otherwise a robot or any software that doesn't read HTML will never know that a password was expected.

(C31) Linking to non-HTML or non-public content

When linking to a non-HTML document, indicate the type and, if the file is big, also its size, so the user knows what to expect.

When linking to non-public content (password-protected), indicate that, too.

One way to indicate the type of the target is to add the type in square brackets:

… the agenda [PDF]… this video clip [MP4, 16 MB]… a summary [member-only]

(C32) Citations

When copying (quoting) text that is more than four or five words, indicate the source: the name of the author and/or the title of the document, maybe also the year; or link to the source.

When you copy substantial parts (or all) of a document, make sure the copyright license allows that, or get permission from the copyright owner first. (When a document has no explicit license, or a restricted one, it doesn't mean reuse is forbidden, it means you have to ask first.)

(C33) Cool URIs don't change

As Tim explained, a URL, once public, should never again be removed. Choose it wisely (see ‘URLs’). And when the contents at that URL are no longer needed, either make a redirect to what replaces it (and document it, see ‘History of redirects’) or make it clear to a visitor of the page that the content is of historical interest only.

See ‘Examples of outdated pages’ for suggested text and styles.

See ‘How to make redirects’ for ways to create redirects.

(C34) Shorten the text

When writing longer texts (blogs, manuals, press releases, tutorials, etc.) it is easy to write too much. It is a good idea to go through the paragraphs and try to remove what isn't critical or necessary.

Likewise, check each sentence to remove unnecessary words. Words like ‘very’, ‘currently’ or ‘actively’ are often unnecessary.

Orwell's Six Rules contain more good advice on writing clearly.

(C35) Give additional information

You can often help readers by providing information they didn't know they needed. When writing about an event, you can link to similar events. When writing about a technology, you can mention alternatives, derived technologies, implementations and examples. When writing about an organization (working group, meeting, etc.) you can list related organizations.

(C36) Alternative channels

A web page, or a group of related pages, that changes often can benefit from having alternative, ‘push’ channels to its readers, in the form of newsletters, Atom/RSS feeds, or Twitter/Mastodon feeds. That allows readers to come back when there is new information.

Examples of pages that should have at least an Atom/RSS feed: blogs, pages with news and mail archives.

(C37) Easy to unsubscribe

It should be as easy to unsubscribe from a newsletter as it is to subscribe. There should be clear and easy-to-find instructions in the same place as the instructions on how to subscribe.

(C38) Confirmation email

When people unsubscribe from an email list, they should get a confirmation notice.

(C39) No meta-refresh

If you need a redirect, use a proper redirect (HTTP code 301 or 307). That way user agents that do not interpret HTML (i.e., all of them except for browsers) will also understand that they need to look elsewhere.

[It seems browsers don't offer timed reload anymore without browser extensions?] If you have a page that changes often, just tell the users, so they can instruct their browser to reload the page regularly. Users hate it when they go for a coffee and the information that was on their screen has disappeared.

See also the corresponding QA tip.

(C40) Changing documents that should not change

Some documents, or parts of documents, are supposed to be published and not change. Dated technical reports are the obvious example, but also news items, press releases and archived e-mail messages are expected to always stay as they were the day they were published.

Nevertheless, it may be necessary to make changes to them, e.g., to correct factual errors that may have negative effects, remove insults, or remove information that has a negative impact on somebody's life (‘right to be forgotten’). In such a case, the document should clearly indicate

  1. that it has been modified,
  2. the nature of the change, and
  3. the date of the change.

Note that technical reports and e-mail archives have their own, more precise rules, both about how to decide to make a change and how to indicate the change. See the in-place modification policy and the archive editing policy.

(C41) Translations

Link to translations with an anchor written in the language it links to: Nederlands, Français, Русский, 简体中文. After all, the link is meant for people who have trouble reading the English page. But other people may be curious what the link is to, so it is good practice to include a TITLE attribute with the name of the language in the language of the page itself.

Hint: It may be hard to find the name of a language in some other language, especially if you speak neither of them. The list of translations of some popular topic on Wikipedia is a good source. But if in doubt, just put the English name in the TITLE.

(C42) Limited use of cutting-edge features

The use of very recent technology, such as from Recommendations that are less than two years old, should be avoided.

The exception is on pages that are about that technology. They can even show examples of technologies that only have Candidate Recommendation status or equivalent, as long as the maintainer of those pages is able to update them if the specifications for those technologies change.

For example, the SVG home page could include examples of SVG 7 as soon as SVG 7 reaches CR. The Fonts home page should not. On the other hand, the Fonts home page could use WOFF 5 when that specification becomes CR.

In any case, a page that uses recent technology should be functional, if less beautiful, when read with older browsers and other software.

(C43) Pull quotes

Long texts with few section headings may benefit from pull quotes, to show people at a glance what the text is about.

In HTML versions < 5, mark them up with

<blockquote class=doc-pullquote>
  <p>...
</blockquote>

And in HTML5 and higher with

<aside role=doc-pullquote aria-hidden=true>
  <p>...
</aside>

You can leave off the attributes if it is not possible to add them. (E.g., software for blogs or wikis may not allow them.).

See Digital Publishing WAI-ARIA Module 1.0 for more info on the ARIA attributes for pull quotes.

(C44) JavaScript

Pages should not contain JavaScript that changes the content of the page (see ‘Screenscraping’). Scripts that only change the layout are acceptable if there is no solution with a style sheet. (Style sheets are usually faster and especially they are easier for a reader to override.)

Scripts that change the interaction (the way the mouse, keyboard or touch events work) should not be used. They confuse users who don't use the page very often and reduce users' confidence that the page will do what they expect.

The exception are slide shows, because

Visual elements

[Painting: head made out flowers, fruits and vegetables]

Giuseppe Arcimboldo (1527–1593) Vertumnus (1590). Source: Wikipedia

This section collects rules and guidelines about graphical elements of a page: logos, colors, fonts, icons, etc.

Note that the easiest way to apply the right styles for fonts and colors is usually to use one of the existing style sheets under /StyleSheets.

(D1) W3C logo usage

As said in W3C logo, all web pages should have a small W3C logo in the upper left corner. The full rules for using the different W3C logos are below. (These rules are based on and replace the historical rules.)

W3C

The full W3C logo is used in printed materials (e.g., business cards, letterhead, envelopes, folders, labels, folio, T-shirts and bags) and on signage (e.g., banners, architectural signage, display units and conference booths).

The logo is meant to be used on a white background.

Available formats: SVG, PNG, GIF, EPS, Adobe Illustrator (PDF).

This logo was designed in September 1996 by Sally Khudairi and Georges Ouanounou of INRIA.

W3C

Available formats: SVG, PNG, GIF, EPS.

The W3C standalone logo with bars is used for web pages and for signage.

The logo is meant to be used on a white background.

W3C

Available formats: SVG, PNG.

The W3C standalone logo without bars can be used if there is a strong aesthetic reason not to use the bars, if the background is light but not white, or on physical objects (e.g, embroidery, mugs, bags, pins, business card cases and podiums).

W3C

Available formats: SVG, PNG.

The white W3C standalone logo is an alternative to the logo with bars and is meant to be used on a background that is W3C blue (#005a9c) or close to it.

The background of the logo without bars and of the white logo has to extend outside the logo by a certain amount. This is especially so as not to cut off the top of the invisible ‘C’. The padding at the top has to be at least 21% of the height of the logo (i.e, 7px at the default size of 68 by 34px), the padding at the bottom at least 18% (6px at the default size), the padding at the left at least 6% (4px at the default size) and the padding on the right side at least 1.5% (1px).

[diagram of the padding around the logo]

For all of the above, the ALT text should be ‘W3C’.

Note: you may find versions of the logos without the small ® mark on the right. These are old and should not be used.

[Logos for Member, Office, Evangelist…]

[Add a link to the (public) page ‘Logos and icons’ and make sure this guide and that page agree.]

[Images should be replaced by the new (‘revamped’) logos in 2023.]

(D2) Fonts

The font in the W3C logo is Base Twelve Sans from Emigre Graphics.

In print materials, we use Gill Sans for the main body of text.

On the Web, it is not necessary to specify fonts, allowing the reader to read text in their preferred font. If you do specify fonts, one good combination is Gill Sans for the body text, with headings in the normal weight (not bold) of OFL Sorts Mill Goudy. (OFL Sorts Mill Goudy is a free font, derived from Goudy.)

Note that Gill Sans is only available for the Latin and Cyrillic scripts. Noto Sans may be an alternative for most other scripts.

Line height in the main text should be between 1.3 and 1.5. It may be more in certain environments, in particular in forms; and should be less in headings when they have a larger font size than the main text.

When choosing the line height, take into account the following important factors:

If you specify fonts, you can use WebFonts to make sure that people see a page with the intended font (at least if they have CSS turned on). There is a shared collection of WebFonts under /assets/fonts/ (including Gill Sans, Noto Sans, OFL Sorts Mill Goudy and League Gothic Regular) with instructions for use. [Check that this is true.]

When you make a new WebFont, it is recommended to install it under that directory, so that others can find it and reuse it without duplicating effort. Please, add some documentation and/or an example of its use (and sign and date it).

If you plan to use a WebFont other than those mentioned above for the body text or the headings, please see with the Communications Team first, to verify if it fits in the W3C style.

[Google's fonts have a license that allows them to be used directly from their CDN, i.e., without the need to install copies on our server. Do we recommend that?]

(D3) Font size

The font size of the main body should be left to the reader (i.e., it should not be specified, or specified as 1em or medium). Smaller text (no smaller than 90%) may be used only for very short, footnote-like pieces of text. Bigger text can be used te emphasize blocks of text or for headings.

(D4) Heading style

Headings h1, h2 and h3 are in normal weight.

See ‘Fonts’ for guidelines about font families, ‘Lowercase headings’ for capitalization, and ‘Heading colors’ for colors.

(D5) Colors

When you need colors (besides black and white), pick them primarily from the W3C blue (#005a9c [color sample]) and the contrasting orange (#cb6628 [color sample]), or from lighter, darker or greyer variants of these. (This is most easily done with the hsl() color notation in CSS: just keep the hue at 205 or 23. See the figure below for examples.)

The blues should be dominant, the oranges should occur only in small quantities,

hsl(205,100%,18%), #00355bhsl(205,100%,25%), #004a7fhsl(205,100%,28%), #00538ehsl(205,100%,31%), #005a9c
W3C blue
hsl(205,100%,34%), #0065adhsl(205,81%,34%), #10629chsl(205,100%,38%), #0071c1hsl(205,60%,38%), #266a9bhsl(205,16%,54%), #758c9chsl(205,42%,90%), #dae7f0hsl(23,70%,38%), #c16125hsl(23,67%,48%), #cb6628
contrast orange
hsl(23,54%,56%)hsl(23,44%,64%), #cb997a

Some variations of W3C blue and contrast orange.

When printing with a Pantone-based process, use Pantone 293C. The ‘C’ means the color as it appears on coated paper. If unavailable, Pantone Reflex Blue may be used instead. (Pantone-based color printing means printing with pre-mixed dyes, as apposed to a four-color process, in which cyan, magenta, yellow and black inks are overprinted to produce a desired color. It is rare for paper, but it may occur for printing on objects.)

(This section replaces the page W3C brand colors. That page still has some useful advice.)

(D6) Text color

The main text on a page should be black on white. Blocks of text can be set off with a background of #f1f7fb (a light blue), #dae4f0 (another light blue) or #eeeeee (a light gray).

Short pieces of text (menu, title, button, motto, etc.) may also have white text on blue: #084b7b (a dark blue), #005a9c (W3C blue).

black on white
#fff
black on #eff5fa
hsl(205,56%,96%)
black on #dae7f0
hsl(205,42%,90%)
black on #eeeeee
hsl(0,0%,93%)
white on #084b7b
hsl(205,87%,26%)
white on #005a9c
hsl(205,100%,31%)
(W3C blue)

Colors for text

In the case of small blocks of text, the background may also be a very slight color gradient centered around one of these colors. The darkest blue background may also have a subtle pattern.

The background of text blocks with a colored background should have a visual padding of between 1 and 2 rem. I.e., the background should extend above, below and on the sides of the text by one to two times the font size of the main text. Note that there are different ways to achieve this in CSS. What counts is the final visual effect.

This padding should be consistent for all colored blocks on the page.

(D8) Heading colors

Headings should be the same color as the text after them (except in technical reports, which have headings in W3C blue).

[If we do want a color for headings, it should probably not be blue, despite the TRs. TRs don't have headings that are links, but other pages may. The current W3C home page, e.g., has many headings that are links, and the fact that links and headings have the same color makes it impossible to know if a heading is clickable, other than by putting the mouse pointer or the focus on it.]

(D9) Underline

Avoid underlining text that is not a hyperlink. Readers expect that underlined text is clickable.

(D10) Icons

[… library of icons for certain concepts (e.g., search, atom feeds, ); visual style of additional icons…]

Icons that are shared by several pages can usually be found under /Icons/ and new, shared icons should be placed there. Some icons for slide presentations are under /Talks/Icons/.

See Appendix D for more collections of icons.

(D11) Signature style

The author's name and copyright statement at the bottom of a page should be in an address element and in italics or oblique (which is the default style for address in most browsers, even without CSS).

(D12) Animation

Avoid animation for decorative purposes. Animation can be used for two purposes: (1) in a graphic, if something is better explained by showing a change occurring, e.g., how a scrollbar works or how a horse's trot differs from galop; and (2) in the form of a short (less than half a second), one-time transition.

A short transition is actually a good way to give visual feedback after a user action. E.g., if a clicked button changes color, changing the color over 0.2 seconds instead of immediately makes the effect more visible and more natural, without slowing the user down. (The CSS property ‘transition’ is ideally suited for this kind of use.)

If you do use animation to attract attention, make sure that you don't use fast blinking (an accessibility problem) and that the animation either stops by itself after ten seconds or so, or that the user can turn it off.

Also watch out for unintended fast blinking, due to elements appearing too briefly on key or mouse actions.

For an example of a purely decorative animation that the user can turn off, see some balloons animated through CSS or the CSS20 animated GIF.

(D13) Similar pages

Pages that have similar roles should look similar. It is a good idea to look for existing pages on our sites that fulfill similar purposes and copy visual elements from those. For example, there are many pages that present news items, a calendar of events, a Working Group, an email archive, an online survey (questionnaire), a specification, a list of contacts, a technology (an area home page), meeting minutes or a meeting agenda.

If our existing pages don't provide clear visual elements, look elsewhere on the Web for the typical look of pages of that kind.

The goal is that people, at least those that come to our site more than once, can see immediately that a page is a specification, or that it provides news items, etc.

See also Appendix C for some example pages.

Structure of our web site and URLs

[Painting: impressionist painting of a stone and steel bridge, with small boats]

Claude Monet (1840–1926): La seine à Argenteuil (1874). Source: Neue Pinkothek, München CC BY-SA 4.0

(E1) URLs

Two of the goals that guide the creation of URLs are (1) a URL is just an identifier for a resource, it says nothing about the contents of the resource; and (2) a URL can be written on a napkin. Unfortunately, those two conflict somewhat. To be able to decipher a URL on a napkin, it better be short and consist of actual words. But choose words that don't risk to contradict the contents when the document evolves over time.

To make communicating URLs a little easier, our server automatically corrects for upper- and lowercase. E.g., https://www.w3.org/markup and https://www.w3.org/MarkUp give the same result. (The actual directory is called MarkUp.)

(E2) Default file names

The default file in a directory (the file that will be served in response to a URL that ends with a slash) is called ‘Overview.html’. Sometimes it is ‘Overview.xhtml’ and in some directories, especially those with slides, we have also used ‘all.htm’ or ‘index.html’. It is possible to change the default for individual directories, but it is easier to manage the site if directories are consistent. Unless there is a very good reason to do otherwise, stick with ‘Overview.html’.

(E3) Non-HTML content

Whenever possible, use HTML for text documents and JPEG, PNG, GIF and SVG for graphics. If necessary, PDF and plain text are also possible, because nearly everybody has a viewer for those. Avoid using other formats for text, such as Powerpoint, Keynote or MS Word.

MP3 (‘.mp3’) is the most widely supported audio format. Opus (‘.opus’) is a newer format with higher quality and is expected to replace it. As of 2020, the major desktop and mobile operating systems and browsers support it, but as older versions do not, it is not yet recommended for our site, unless with a fallback. In HTML5, the audio element allows to specify multiple alternative sound files as separate source child elements.:

<audio controls>
<source src="my-audio.opus" type="audio/ogg">
<source src="my-audio.mp3" type="audio/mpeg">
<a href="my-audio.opus">my audio</a>
</audio>

For video, the situation is less clear: MP4 (‘.mp4’) and MKV/WebM (‘.mkv’ or ‘.webm’) are the most widely supported container formats, with H.264 and VP9 the most widely implemented compression formats. It may be necessary to provide two versions of each video: MP4/H.264 and WebM/VP9. E.g., with the HTML5 <video> element:

<video controls>
<source src="my-video.mp4" type="video/mp4">
<source src="my-video.webm" type="video/webm">
<a href="my-video.mp4">my video</a>
</video>

Do not include JavaScript players for any of the above formats. The best player is always the native one on the user's machine (which is often the user's browser itself.) Downloading a large JavaScript program is also slow; the program is unlikely to work on a mobile phone; and linking to the program instead of the resource itself makes it hard for a user without JavaScript (including non-human users, such as web spiders) to see the resource (unless there is also a direct link to the resource).

Maintenance

[Painting: A carpenter bores a hole in a piece of wood, while he is lighted by a boy with a candle]

Georges de La Tour (1593–1652): Saint Joseph charpentier (±1640). Source: Wikipedia

(F1) History of changes

Document all changes (what, when, why). Take into account that some day somebody else may have to take over maintenance. If the resource is under version control (e.g., CVS), use its logs. Otherwise track the important changes using embedded comments or in a README file in the same directory. But don't make the documentation longer than necessary either. E.g., for simple spelling correction, writing just ‘Typos’ in the log suffices.

If you are not using CVS directly, but update pages via HTTP (i.e., Webdav or HTTP PUT, e.g., with BlueGriffon or curl), you are not prompted for a log entry. Please, try to write a log entry anyway for any non-trival change, by going to the online CVS form. It can be found as follows: If you edited a page with a URL of https://www.w3.org/path/to/file.html, then open the URL https://edit.w3.org/path/to/file.html?log.

If you update pages indirectly by changing something in an online form, the form may have a way to add comments.

(F2) History of redirects

When a document moves or is renamed, a redirect is normally left in place. Document the redirect, if possible both in the old location and in the new, so that the history of the document can be traced across the name change. (There are various techniques for making redirects, see ‘How to make redirects’ in the appendix.)

If making the redirect involves creating or changing files, their CVS logs are good places for such documentation.

(F3) Content review

One way to improve and maintain the quality of our sites is to review each other's pages. Make a habit of reviewing arbitrary pages every once in a while and send feedback to the maintainers, even if you found nothing wrong.

Apart from looking for obvious spelling errors or factual errors, try to estimate by when the page would need an update.

Area pages

[Painting: several long and short horizontal and vertical black lines forming rectangles of various sizes, some of which are filled with blue, red or yellow.]

Piet Mondrian (1872–1944): Trafalgar_Square (1943). Source: Wikipedia

(G1) Area home page

All our technical areas should have a home page, although closely related technologies can be combined on one page. This page can talk about the WG(s) in that area, but should be useful also for people not interested in the WG and should be designed such that it can survive any WGs.

Group pages

[Painting: a group of men sitting and standing behind a long table, discussing in small groups]

Leonardo da Vinci (1452–1519): Ultima Cena (1498). Source: Wikipedia

(H1) Group home page

Working groups should have a public home page (different from the home page of the area to which the group belongs) and also a member-only home page. The latter is for confidential information, such as phone numbers and videoconference passwords. The former serves, among other things, to identify the group in the status section of Technical Reports.

There should probably be some templates, which staff contacts can use as the basis for new pages of both kinds, but currently there aren't. When there are, they will listed in appendix C.

Workshop pages

[Print: An 18th century Japanese workshop with women making prints]

Utagawa Kunisada (1786–1865): Printmaking triptych (<1865). Source: Wikipedia

This section contains additional rules and recommendation for workshop pages. See also the appendix for some templates and examples.

(I1) Structure

A separate page describes the process for organizing a workshop and the information on workshop pages.

Mail archives

[Painting: Sitting woman with a lute and a letter talking to a standign woman, in a 1th century Dutch interior]

Johannes Vermeer (1632–1675): De liefdesbrief (±1669). Source: Wikipedia

This section contains rules that only apply to pages that are part of an email archive.

[…]

TPAC and AC

TPAC and AC meeting pages, apart from being W3C pages, also have an identity as part of the TPAC and AC series.

The Events Team coordinates their development and writes most of the content, the Web Design Task Force of the Comm Team does the layout. Please, contact either team when changes are needed in TPAC or AC material.

(K1) TPAC/AC style

A new style was made for TPAC 2019 and enhanced further for AC 2020 and TPAC 2020. This style is meant to be reused, with minor variations (notably the artwork) for future TPAC and AC meeting pages. Instructions for authors are in the user manual.

(K2) Printed agenda

One characteristics of TPAC and AC pages is that a part of their content is also made into a hand-out that is given to participants at the registration.

The recommended practice is to base the hand-out on the page with the detailed schedule. That page is printed after applying a style sheet that is optimised for printing. This ‘single source’ process avoids inconsistencies or omissions and reduces the work.

Parts of the page that are only relevant online (such as how to register) or only relevant when printed (e.g., visible URLs) can be specially marked up to hide them from view.

The printed and online styles are different, but related. They use the same fonts, same logos, same overall organization of the page, and the same colors, but details differ: the colors may be used in different places (e.g., colored backgrounds vs colored borders), the text may be justified on paper, the printed page has page numbers, different margins, etc.

(K3) Signs and posters

Information boards or signposts at the TPAC venue (e.g., lists of meeting rooms and meeting times, directions to the registration desk), should use the same style as the handout (colors, fonts, logos), adapted to the format of the signage.

It is recommended to generate these from the same source as the handout, to avoid inconsistencies, at least if they contain room and time schedules. This online PDF generator was used in 2019. (It may need to be updated.)

Depending on the venue, some of the signage may be displayed on monitors instead of printed on paper or plastic. The size of the signs may also depend on the venue (American or ISO print sizes, size of display stands). To avoid requiring the intervention of designers for every variation, ask the Web Design Task Force for one or two templates. The meeting organizers can then fill these with different content. A template could, e.g., be in the form of a Powerpoint slide with the artwork already in place and an empty box for text.

(K4) Name badges

Name badges shoould contain a recognizable element from the TPAC or AC pages, such as a fragment of the banner image.

Printing of the badges can be left to a local printer (except for a few blanks held in reserve for on-site registration), which means creating artwork that can be given to the printer (usually in PDF), but leaving the details of the design to the printer.

(K5) TPAC & AC slides

Usually, (the Web Design Task Force of) the Comm Team prepares slide templates for talks at AC and TPAC meetings with the specific visuals of that meeting. (Example: the template for TPAC 2019 slides.)

Team-only pages

[Prehistoric painting: several heads of European Cave Lions]

Lions in the Chauvet Cave (20th century replica, based on original of ±35000 BC), Source: Wikipedia

(L1) Quality of team-only pages

The intranet doesn't have quite the same quality requirements as the public or member pages, but a page that looks nice, contains no spelling errors, and fits the style and structure of the rest of the intranet is still easier to read. Balance the time you spend on improving the page against the time lost by your colleagues when the page is of poor quality.

(L2) Team colors

It is recommended to give team-only pages black text on a background color of #fff6e0 ([color sample]). #fff6e0 is a color close to beige. A subtle color gradient around this color is also possible, such as this horizontal gradient in CSS:

linear-gradient(90deg, hsl(43, 100%, 93%), hsl(43, 100%, 96%), hsl(43, 100%, 93%))

The background should also have the icon of the small coffee cup on a red background (see the image below) fixed in the upper red corner. The simplest is to include this style sheet:

https://www.w3.org/StyleSheets/team.css

For examples, see Appendix C, ‘Templates and examples’

[image: red vertical bar with a small white coffee cup near the top]

Image to put in the background of team-only pages, fixed to the upper right corner

(L3) Team icons and navigation

Team-only pages should have the coffee maker logo ([image: Italian coffee cooker]) next to the W3C logo, with a link to https://www.w3.org/Team/, e.g., like this:

<a href="../../Team/" ><img src="../../Icons/WWW/team" alt="Team"></a>

Other forms of communication

W3C communicates not only via its websites, but also via Atom/RSS, email, Twitter, Mastodon, brochures, talks at conferences, booths at trade shows, videos and maybe more. These communication channels have their specific restrictions on content and style, but where possible the guidelines of this style guide should be applied: writing style, spelling, use of the W3C logo and colors, etc.

(M1) Business cards

Business cards contain the main W3C logo (which includes the full name ‘World Wide Web Consortium’):

W3C logo (W3C - World Wide Web Consortium)

The font is Gill Sans. Here is an example:

[image: business card of Bert Bos]

The backsize may contain different languages (which may require a different font than Gill Sans, e.g., Noto Sans). Having the main information of the card in braille (embossed) is also a nice touch.

(M2) Microblogging

Microblogging means publishing very short texts (less than about 500 characters), possibly accompanied by some images and on channels dedicated to such messages. The current (2019) ones in operation are Twitter and Mastodon.

See the separate pages about ‘W3C micro-blogging + Social Media’ and the ‘W3C Twitter FAQ’.

(M3) Social media

See the ‘W3C Social Media Participation Guidelines’.

(M4) Slides and conference talks

For certain events, in particular each AC and TPAC meeting, the Communications team prepares slide templates with the visual style for that event.

Some conferences require slides to use a certain style, or require the style to conform to certain rules. E.g., there are conferences that ask that all presentations have slides with white text on a black background.

For other cases, we have templates with the W3C logo and colors, see the appendix ‘Templates and examples’. (For background and a history of styles for talks, see ‘Slide tools’.)

Of course, we prefer slides in HTML and/or SVG, our own technologies, because the slides can be put online after (or even before) the presentation and don't require the reader to install any extra software.

(M5) Atom/RSS feeds

See ‘Alternative channels’ above.

(M6) Freebies

Gifts for participants at events (T-shirts, mugs, pens, caps, scarves, bags, umbrellas, notepads, etc.) should carry

and also, if not part of the logo:

If possible, either

should be added. The latter may be reduced to just ‘www.w3.org’. [‘w3.org’ seems too short…]

(M7) Videos

See the Policies for Media archiving at W3C, which includes in particular the Multimedia Accessibility FAQ.

(M8) Printed material

As said in ‘Fonts’ above, the font for printed material is Gill Sans (at least for material in the Latin script).

[…]

For guidelines about printed material for TPAC and AC meetings, see ‘Printed agenda’, ‘Signs and posters’ and ‘Name badges’.

(M9) Newsletters and other mailings

See ‘Alternative channels’ for when to use newsletters or other mailings. It should be easy for people to unsubscribe from repeated mailings, see ‘Easy to unsubscribe’.

[Other guidelines…]

Appendix A. Best practices for CSS

When using CSS in a web page, it is usually best to link to the most appropriate style sheet(s) under /StyleSheets and then locally override style rules as needed. This is better than writing a new style from scratch, because there is a good chance that changes to the site style automatically benefit your page as well; and, assuming people read more than one page on our site, they have to download fewer style sheets, which makes pages appear on the screen faster.

Note, however, that for Technical Reports there is a different rule. The pubrules require that the appropriate style sheet is loaded after any local rules. I.e., the site style can override the page's local styles, instead of the other way round.

Appendix B. Best practices for HTML

When a phrase is enclosed in both an <a> and some other element, put the <a> outside. Being consistent makes sharing style sheets and scripts easier. And when a list of anchors is extracted from a document, the anchors will be shown in the right style. Example:

<a href="#open"><code>open()</code></a>

When writing in HTML5, use its ability to specify alternative images to provide SVG to recent user agents and PNG as fallback for older ones.

Also, whether writing in HTML5 or another format (HTML, XHTML), leave off the file extension on the default link, to let user agents negotiate the best format with the server. (Sometimes a browser prefers GIF, or the server prefers it, because it is smaller. Or we make additional formats available later.) In its simplest form, that looks like this:

<img srcset="../../Icons/w3c_icon.svg" src="../../Icons/w3c_home" alt="W3C">

The W3C logo can be included by linking to an image under https://www.w3.org/Icons/, but it is also acceptable to include the SVG code of the logo directly in the HTML source. This only works in HTML5. Be sure to include a fallback for older browsers. In the code below, the fallback is an <img> element.

<a href="/"><svg role="img" aria-label="W3C" viewBox="0 0 68 34" width="68px" height="34px"> <desc><img src="../../../Icons/WWW/w3c_home_nb_transp.png" alt="W3C"></desc> <path fill="#005A9C" d="m16.117 1.006 5.759 19.58 5.759 -19.58h4.17 11.444v1.946l -5.879 10.128c2.065.663 3.627 1.868 4.686 3.615 1.059 1.748 1.589 3.799 1.589 6.155 0 2.914 -.775 5.363 -2.324 7.348s -3.555 2.978 -6.017 2.978c -1.854 0 -3.469 -.589 -4.845 -1.767 -1.377 -1.178 -2.396 -2.773 -3.058 -4.786l3.256 -1.35c.477 1.218 1.106 2.178 1.887 2.879.781.702 1.701 1.052 2.76 1.052 1.112 0 2.052 -.622 2.82 -1.866.768 -1.245 1.152 -2.74 1.152 -4.489 0 -1.933 -.411 -3.429 -1.231 -4.488 -.954 -1.244 -2.45 -1.867 -4.489 -1.867h -1.588v -1.906l5.56 -9.612h -6.712l -.382.65 -8.163 27.548h -.397l -5.958 -19.937 -5.957 19.937h -.397l -9.53 -32.168h4.17l5.759 19.58 3.892 -13.185 -1.906 -6.395z"></path> <path d="m64.92 1.006c -.819 0 -1.554.295 -2.111.861 -.591.6 -.92 1.376 -.92 2.178s.313 1.545.887 2.128c.583.591 1.334.912 2.145.912.793 0 1.562 -.321 2.161 -.903.574 -.557.887 -1.3.887 -2.136 0 -.811 -.321 -1.57 -.878 -2.136 -.584 -.592 -1.344 -.904 -2.171 -.904zm2.643 3.065c0 .701 -.271 1.351 -.768 1.832 -.524.507 -1.174.777 -1.892.777 -.675 0 -1.342 -.278 -1.84 -.785s -.777 -1.157 -.777 -1.849.287 -1.368.802 -1.891c.481 -.49 1.131 -.751 1.84 -.751.726 0 1.376.271 1.883.785.49.489.752 1.147.752 1.882zm -2.559 -1.807h -1.3v3.445h.65v -1.469h.642l.701 1.469h.726l -.769 -1.57c.498 -.102.785 -.439.785 -.929 0 -.625 -.472 -.946 -1.435 -.946zm -.118.422c.608 0 .886.169.886.591 0 .405 -.278.549 -.87.549h -.549v -1.14z"></path> <path d="m59.807.825.676 4.107 -2.391 4.575s -.918 -1.941 -2.443 -3.015c -1.285 -.905 -2.122 -1.102 -3.431 -.832 -1.681.347 -3.587 2.357 -4.419 4.835 -.995 2.965 -1.005 4.4 -1.04 5.718 -.056 2.113.277 3.362.277 3.362s -1.452 -2.686 -1.438 -6.62c.009 -2.808.451 -5.354 1.75 -7.867 1.143 -2.209 2.842 -3.535 4.35 -3.691 1.559 -.161 2.791.59 3.743 1.403 1 .854 2.01 2.721 2.01 2.721z"></path> <path d="m60.102 24.063s -1.057 1.889 -1.715 2.617c -.659.728 -1.837 2.01 -3.292 2.651s -2.218.762 -3.656.624c -1.437 -.138 -2.772 -.97 -3.24 -1.317s -1.664 -1.369 -2.34 -2.322 -1.733 -2.859 -1.733 -2.859.589 1.91.958 2.721c.212.467.864 1.894 1.789 3.136.863 1.159 2.539 3.154 5.086 3.604 2.547.451 4.297 -.693 4.73 -.97s1.346 -1.042 1.924 -1.66c.603 -.645 1.174 -1.468 1.49 -1.962.231 -.36.607 -1.092.607 -1.092z"></path> </svg></a>

Because this SVG is so short, this is likely to be more efficient on a single page and the fact that the image cannot be cached does not hinder a lot on multiple pages. [Verify this. Maybe Yves can tell us the details?]. One disadvantage is that it is harder to replace the icon in all pages if we make a new one (as we did when we added the ® mark to the old logo).

But the main advantage is that the SVG can be styled with CSS this way. E.g., the logo can change color when the mouse pointer hovers over it.

Appendix C. Templates and examples

Full-page templates

There are templates available for many types of pages. The templates can serve as a starting point for a new page or just as an example. A simple form helps you fill the template with some essential content, You can then copy & paste the result into your editor or save it to a local file.

On our main site, www.w3.org, there is a simple way to see if there are templates for the page you need: go to an existing page of the right kind and add ‘,new’ after the URL. If there are related templates, they will appear in a list.

Here are some examples. (This list is not exhaustive.)

Examples of signed pages

Here is some suggested markup for the bottom of a page (see ‘Signed’, ‘Last-modified date’, ‘Copyright notice’, Author link’ and ‘Privacy policy’.)

Name, function, email and date:

Bert Bos, style activity lead
Last updated Wed 22 May 2019 11:47:19 PM UTC
Copyrightprivacy policy

<address>
<a href="mailto:bert@w3.org" rel="author">Bert Bos</a>, style activity lead<br>
Last updated Wed 22 May 2019 11:47:19 PM UTC<br>
<a rel="copyright" href="../../Consortium/Legal/ipr-notice#Copyright" >Copyright</a> – <a href="../../Consortium/Legal/privacy-statement-20140324" >privacy policy</a>
</address>

You can see a similar example at the bottom of this page, which makes use of a CVS keyword to automatically update the date.

If the author's home page contains an email address, it is also possible to link to that home page:

Bert Bos, style activity lead
Last updated Wed 22 May 2019 11:47:19 PM UTC
Copyrightprivacy policy

<address>
<a href= "../../People/Bos/" rel="author">Bert Bos</a>, style activity lead<br>
Last updated Wed 22 May 2019 11:47:19 PM UTC<br>
<a rel="copyright" href="../../Consortium/Legal/ipr-notice#Copyright" >Copyright</a> – <a href="../../Consortium/Legal/privacy-statement-20140324" >privacy policy</a>
</address>

An example with a photo of the author (see ‘Photo of the author’) and microformats markup (see ‘Microformats’):

Bert Bos, style activity lead
Last updated Wed 22 May 2019 11:47:19 PM UTC
Copyrightprivacy policy

<address class="vcard h-card">
<img alt="" class="photo u-photo" src="../../People/Bos/bert3-small.jpg"> <a class="fn url p-name u-email" href="mailto:bert@w3.org" rel="author">Bert Bos</a>, <span class="role p-role">style activity lead</span><br>
Last updated Wed 22 May 2019 11:47:19 PM UTC<br>
<a rel="copyright" href="../../Consortium/Legal/ipr-notice#Copyright" >Copyright</a> <a href="../../Consortium/Legal/privacy-statement-20140324" >privacy policy</a>
</address>

When there is no clear owner (e.g., the page is generated or old):

Webmaster
Last update on: Tue May 7 16:40:53 2019
Copyrightprivacy policy

<address>
<a href="//www.w3.org/Help/Webmaster">Webmaster</a><br>
Last update on: Tue May 7 16:40:53 2019<br>
<a rel="copyright" href="../../Consortium/Legal/ipr-notice#Copyright" >Copyright</a> – <a href="../../Consortium/Legal/privacy-statement-20140324" >privacy policy</a>
</address>

Examples of outdated pages

Here are some good ways to indicate in a page that the page is not currently maintained (see ‘Cool URIs don't change’ and ‘Old styles for old pages’).

‘Graying-out’ the page:

<body>
<p style="color: red">This page is currently not maintained.</p>
<div style="opacity: 0.5">
... old content of the page...
</div>
</body>

How to make redirects

There are various ways to make a redirect:

  1. Replace the old document (e.g., ‘foo.html’) with one with the extension ‘.redirect’ (‘foo.redirect’) and give it this content:

    Status: 301 Moved
    Location: https://www.w3.org/People/Pierre/
    Content-Type: text/html
    
    <!DOCTYPE HTML>
    <title>Redirection</title>
    <p>The correct URI for this page is
    <a href="https://www.w3.org/People/Pierre/">
    https://www.w3.org/People/Pierre/</a>.
    

    The empty line above DOCTYPE is required. Of course, you must replace the three occurrences of the URL.

  2. Put a ‘.htaccess’ file in the same directory with an appropriate rule for the Apache server.

  3. Add a redirect rule to the web rewrites list via the online form (‘add new’).

  4. Ask the systems team to add a redirect to the top-level configuration for Apache.

The first method is recommended. The redirection is visible to anybody editing in the same directory and the redirection is easy to make and edit. The last method is not recommended. It leaves no trace in the old location and the top-level configuration file is not visible to everybody.

Appendix D. Collections of graphics

Photos
[local], [Shutterstock team-only], Unsplash, Shutterstock (non-free, see accounts info)
Icons
general icons, slide icons [maybe https://iconmonstr.com/ ?]
Diagrams
Marcomm Design Vault

Appendix E. Word list

Some words and their preferred spelling:

AM
Uppercase, no dots. E.g.: 10:00 AM
back end, back-end, front end, front-end
‘Back end’ is a noun (‘Data is processed by the back end’) and ‘back-end’ is an adjective ('We rely on a back-end server’).
data
Singular: ‘The data is transfered’, not ‘the data are transfered’.
end user, end-user
‘end user’ is a noun, ‘end-user’ is an adjective.
filename
One word.
hostname
One word.
italics
Plural: ‘Italics are used for many things'.
its, it's
‘Its’ is a possessive pronoun, ‘it's’ is short for ‘it is’ or ‘it has’. E.g.: It's a dog wagging its tail. It's been its best year. (See also It's, he's, doesn't…)
log in, login
‘Log in’ is a verb, ‘login’ is an adjective or a noun.
lowercase
One word.
markup
One word, no hyphen.
metadata
One word, no hyphen.
million
Not abbreviated (‘mln’) when inside a sentence. Replace with M (mega) only with care.
mouse click
Two words. Also consider it you actually meant mouse click or just any form of activation, including a finger tap and a key press.
mouse pad
Two words.
no one, nobody
Two words and one word, respectively.
offline, online
No dashes, no spaces.
on screen, onscreen
‘On the screen’ or ‘on screen’ is a prepositional phrase (preposition ‘on’ and noun ‘screen’). E.g.: ‘Show it on the screen.’ The single word ‘onscreen’ is an adjective. E.g.: ‘an onscreen warning’.
pathname
One word.
plug-in
With a hyphen.
PM
Uppercase, no dots. E.g.: 2:00 PM
real-time
One hyphenated word, whether used as noun or as adjective.
style sheet
Two words, except in the expansion of XSL: Extensible Stylesheet Language.
timestamp
One word.
timezone
One word.
uppercase
One word.
usable
Not ‘useable’.
web page
Two words.
website
One word.
zeros
Not zeroes.

(Some of these spelling recommendations come from the recommendations for Unix man pages, man-pages(7).)

Maintainer: Bert Bos. Created: 27 July 2018.
Last modified: $Date: 2022/08/15 21:08:19 $ by $Author: bbos $