CSSWG Spec Markup

This page will eventually document the CSSWG’s spec markup and serve as a manual. Currently it is serving as a scratchspace.

The style sheet that implements most of our special markup has a master on dev.w3.org.

[!NOTE] Note that the CSSWG also uses a post-processor that generates section numbers, cross-references, indices, etc. Such macros are not documented here, but may be documented in a separate document.

Stage 1: Margins, Spacing, and Lists

The CSS specs use lists in a variety of ways:

as logically belonging to a paragraph (sometimes as a continuation of the last sentence in the previous paragraph, which may or may not continue in the next paragraph). (example)
as a paragraph-level structure (example). This is the most common.
as a higher-level structure that contains paragraphs. (example, example)

Definition lists in particular have several uses

They are used to define CSS values. (example) These should be marked up with <dt>, , and , but are often missing one or the other.
They are used for defining other terms, e.g. in a glossary. (example, example) These should use also.
They may be used in some other random applications for which the structure is appropriate (🚧 need to track down examples).

Paragraph, heading, and list margins and spacing should be designed in a way that appropriately handles these structures.

Stage 2: Inline Styling

CSS specs use a variety of inline markup:

: for CSS property names
: for abitrary CSS snippets and CSS values
: for the defining instance of a term, whether in a <dl> or in a paragraph. Must be easily scannable
: for instance-of-term; this auto-links to the defining instance, if there is one in the spec. These are used very very frequently in some cases (example, example) so their styling should not be distracting.

: for other kinds of cross-linking

and : used per HTML5 (but are fairly uncommon); default styling should be fine

: for variables in mathematical or syntactical formulas

Stage 3: Tables

Specs use tables for data. In some cases, we have some very complex table structures, which should be styled appropriately. Writing modes and Text have some good examples: (simple table, super-complex table, common-complexity table, another example)

We also use tables for indices, like the full property index and the selectors overview.

Stage 4: Notes, Issues, Examples, and other Boxen

The CSSWG uses some colored boxes to delineate special types of information.

: Examples are non-normative and relatively self-contained. They often, but not always, illustrate a normative definition immediately before the example. They might contain only text; text and code; text and a figure; text, some code, and a figure; or several repetitions of these. They need to be clearly delineated so that readers can tell that the text is non-normative. They are also things authors like to scan for.

: Like examples, figures are also used to illustrate the normative text (and in some cases are used in informative sections like examples and notes, too!) They usually come with a caption and must have alternative text for non-sighted readers. ([examples inside examples](http://dev.w3.org/csswg/css3-background/#the-background-position), [Writing Modes is full of examples](http://dev.w3.org/csswg/css3-writing-modes/)) : Propdef tables contain the critical information for a property definition. They must be easily scannable. ([example](http://w3c-test.org/csswg/css3-background/#the-background-clip), [consecutive-boxes example](http://w3c-test.org/csswg/css3-break/#break-properties)) ,

: Notes are non-normative sentences (inline) or paragraphs (or multi-paragraphs) that help explain the implications of some normative text. It needs to be clear that they are not normative, but they also should not jump out of the text, as they are not something to scan for but a continuation of the normative discussion. [example](http://w3c-test.org/csswg/css3-background/#the-background-clip)

: These  boxes are typically normative; they unambiguously define the syntax of a feature in code. They often contain a  defining a grammar production that is reused later. ([example](http://dev.w3.org/csswg/css3-images/#linear-gradients), [example](http://w3c-test.org/csswg/css3-background/#the-background-position))

, , 

: Issues are notes from the editor to reviewers. They document areas that need more feedback, and explain problems that are as-yet unresolved in the specs. They are used in Working Drafts: CRs and beyond are not supposed to have issues.