<pre class=metadata>

Title: CSS Counter Styles Level 3

Shortname: css-counter-styles

Level: 3

Status: ED

Work Status: Testing

Group: csswg

ED: https://drafts.csswg.org/css-counter-styles/

TR: https://www.w3.org/TR/css-counter-styles-3/

Previous Version: https://www.w3.org/TR/2017/CR-css-counter-styles-3-20171214/

Previous Version: https://www.w3.org/TR/2015/CR-css-counter-styles-3-20150611/

Previous Version: https://www.w3.org/TR/2014/WD-css-counter-styles-3-20140826/

Previous Version: https://www.w3.org/TR/2013/WD-css-counter-styles-3-20130718/

Previous Version: https://www.w3.org/TR/2013/WD-css-counter-styles-3-20130221/

Previous Version: https://www.w3.org/TR/2012/WD-css-counter-styles-3-20121009/

Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199

Abstract: This module introduces the ''@counter-style'' rule, which allows authors to define their own custom counter styles for use with CSS list-marker and generated-content counters [[CSS-LISTS-3]]. It also predefines a set of common counter styles, including the ones present in CSS2 and CSS2.1.

Link Defaults: css-text-3 (dfn) grapheme cluster, css-pseudo-4 (selector) ::marker, dom-ls (dfn) ASCII case-insensitive

Deadline: 2015-05-03

At Risk: the <<image>> value in <<symbol>>

</pre>

<style>

pre.stylesheet { white-space: pre-wrap; }

code.inline { display: inline-block; }

</style>

<pre class=link-defaults>

spec:css-text-3; type:dfn; text: grapheme cluster

spec:css-pseudo-4; type:selector; text: ::marker

spec:dom; type:dfn; text: ASCII case-insensitive

spec:css-values-3; type:dfn; text:identifier

</pre>

<h2 id='intro'>

Introduction</h2>

CSS 1 defined a handful of useful counter styles based on the styles that HTML traditionally allowed on ordered and unordered lists.

While this was expanded slightly by CSS2.1,

it doesn't address the needs of worldwide typography.

This module introduces the ''@counter-style'' rule which allows CSS to address this in an open-ended manner,

by allowing the author to define their own counter styles.

These styles can then be used in the 'list-style-type' property

or in the ''counter()'' and ''counters()'' functions.

It also defines some additional predefined counter styles,

particularly ones which are common but complicated to represent with ''@counter-style''.

<h2 id='counter-styles'>

Counter Styles</h2>

A <dfn export>counter style</dfn> defines how to convert a counter value into a string.

Counter styles are composed of:

<ul>

<li>

a name,

to identify the style

<li>

an algorithm,

which transforms integer counter values into a basic string representation

<li>

a negative sign,

which is prepended or appended to the representation of a negative counter value.

<li>

a prefix,

to prepend to the representation

<li>

a suffix

to append to the representation

<li>

a range,

which limits the values that a counter style handles

<li>

a spoken form,

which describes how to read out the counter style in a speech synthesizer

<li>

and a fallback style,

to render the representation with when the counter value is outside the counter style's range

or the counter style otherwise can't render the counter value

</ul>

When asked to <dfn export lt='generate a counter|generate a counter representation'>generate a counter representation</dfn>

using a particular counter style for a particular counter value,

follow these steps:

<ol>

<li>

If the counter style is unknown,

exit this algorithm and instead <a>generate a counter representation</a>

using the ''decimal'' style and the same counter value.

<li>

If the counter value is outside the '@counter-style/range' of the counter style,

exit this algorithm and instead <a>generate a counter representation</a>

using the counter style's fallback style and the same counter value.

<li>

Using the counter value and the counter algorithm for the counter style,

generate an <dfn>initial representation for the counter value</dfn>.

If the counter value is negative

and the counter style <a>uses a negative sign</a>,

instead generate an initial representation using the absolute value of the counter value.

<li>

Prepend symbols to the representation as specified in the '@counter-style/pad' descriptor.

<li>

If the counter value is negative

and the counter style <a>uses a negative sign</a>,

wrap the representation in the counter style's negative sign

as specified in the '@counter-style/negative' descriptor.

<li>

Return the representation.

</ol>

Note: '@counter-style/prefix' and '@counter-style/suffix' don't play a part in this algorithm.

This is intentional;

the prefix and suffix aren't part of the string returned by the counter() or counters() functions.

Instead, the prefix and suffix are added by the algorithm that constructs the value of the 'content' property

for the ''::marker'' pseudo-element.

This also implies that the prefix and suffix always come from the specified counter-style,

even if the actual representation is constructed by a fallback style.

Some values of '@counter-style/system' (''symbolic'', ''additive'')

and some descriptors ('@counter-style/pad')

can generate representations with size linear to an author-supplied number.

This can potentially be abused to generate excessively large representations

and consume undue amounts of the user's memory or even hang their browser.

User agents must support representations at least 60 Unicode codepoints long,

but they may choose to instead use the fallback style for representations that would be longer than 60 codepoints.

<!--

███████ ██████ ███████ ██ ██ ██ ██ ████████ ████████ ████████ ██████ ████████ ██ ██ ██ ████████

██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ███ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██

██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██████ ████████ ███████ ██████ ██ ██ ██ ██████

██ █████ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

███████ ██████ ███████ ███████ ██ ██ ██ ████████ ██ ██ ██████ ██ ██ ████████ ████████

-->

<h2 id='the-counter-style-rule'>

Defining Custom Counter Styles: the ''@counter-style'' rule</h2>

The <dfn at-rule>@counter-style</dfn> rule allows authors to define a custom <a>counter style</a>.

The components of a <a>counter style</a> are specified by descriptors in the ''@counter-style'' rule.

The algorithm is specified implicitly by a combination of the ''@counter-style/system'', ''@counter-style/symbols'', and ''@counter-style/additive-symbols'' properties.

The general form of an ''@counter-style'' rule is:

<pre class=prod>

@counter-style <<counter-style-name>> { <<declaration-list>> }

</pre>

<dfn>&lt;counter-style-name></dfn> is a <<custom-ident>>

that is not an <a>ASCII case-insensitive</a> match for ''list-style-type/none''.

When used here, to define a counter style,

it also cannot be any of the [=non-overridable counter-style names=]

(in other uses that merely reference a counter style,

such as the ''extend'' system,

these are allowed).

The <<counter-style-name>> is a [=tree-scoped name=].

The <dfn>non-overridable counter-style names</dfn> are

the keywords ''decimal'', ''disc'', ''square'', ''circle'', ''disclosure-open'', and ''disclosure-closed''.

Note: Note that <<custom-ident>> also automatically excludes the <a spec=css-values>CSS-wide keywords</a>.

In addition, some names, like ''inside'',

are valid as counter style names,

but conflict with the existing values of properties like 'list-style',

and so won't be usable there.

Counter style names are case-sensitive.

However, the names defined in this specification are ASCII lowercased on parse

wherever they are used as counter styles, e.g.

in the 'list-style' set of properties,

in the ''@counter-style'' rule,

and in the ''counter()'' functions.

Each ''@counter-style'' rule specifies a value for every counter-style descriptor,

either implicitly or explicitly.

Those not given explicit value in the rule take the initial value listed with each descriptor in this specification.

These descriptors apply solely within the context of the ''@counter-style'' rule in which they are defined,

and do not apply to document language elements.

There is no notion of which elements the descriptors apply to or whether the values are inherited by child elements.

When a given descriptor occurs multiple times in a given ''@counter-style'' rule,

only the last-specified valid value is used;

all prior values for that descriptor must be ignored.

Defining a ''@counter-style'' makes it available to the entire document in which it is included.

If multiple ''@counter-style'' rules are defined with the same name,

only one wins,

according to standard cascade rules.

''@counter-style'' rules cascade "atomically":

if one replaces another of the same name,

it replaces it <em>entirely</em>,

rather than just replacing the specific descriptors it specifies.

Note: Note that even the predefined counter styles can be overridden;

the UA stylesheet occurs before any other stylesheets,

so the predefined ones always lose in the cascade.

This at-rule conforms with the forward-compatible parsing requirement of CSS;

conformant parsers that don't understand these rules will ignore them without error.

Any descriptors that are not recognized or implemented by a given user agent,

or whose value does not match the grammars given here or in a future version of this specification,

must be ignored in their entirety;

they do not make the ''@counter-style'' rule invalid.

<!--

██████ ██ ██ ██████ ████████ ████████ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ███ ███

██ ████ ██ ██ ██ ████ ████

██████ ██ ██████ ██ ██████ ██ ███ ██

██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██

██████ ██ ██████ ██ ████████ ██ ██

-->

<h3 id='counter-style-system'>

Counter algorithms: the '@counter-style/system' descriptor</h3>

<pre class='descdef'>

Name: system

For: @counter-style

Value: cyclic | numeric | alphabetic | symbolic | additive | <span class=nobr>[fixed <<integer>>?]</span> | <span class=nobr>[ extends <<counter-style-name>> ]</span>

Initial: symbolic

</pre>

The '@counter-style/system' descriptor specifies which algorithm will be used to construct

the counter's representation based on the counter value. For example,

''cyclic'' counter styles just cycle through their symbols repeatedly,

while ''system/numeric'' counter styles interpret their symbols as digits and

build their representation accordingly.

The systems are defined in the following subsections.

Each '@counter-style/system' value is associated with either the '@counter-style/symbols' or '@counter-style/additive-symbols' descriptors,

and has a minimum length that the appropriate descriptor must have;

each entry below defines what this is.

If a ''@counter-style'' rule fails to meet this requirement,

it does not define a [=counter style=].

(The rule is still syntactically valid, but has no effect.)

<!--

██████ ██ ██ ██████ ██ ████ ██████

██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ████ ██ ██ ██ ██

██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██

██████ ██ ██████ ████████ ████ ██████

-->

<h4 id="cyclic-system">

Cycling Symbols: the ''cyclic'' system</h4>

The <dfn value for="@counter-style/system">cyclic</dfn> counter system cycles repeatedly through its provided symbols,

looping back to the beginning when it reaches the end of the list.

It can be used for simple bullets

(just provide a single <a>counter symbol</a>),

or for cycling through multiple symbols.

The first <a>counter symbol</a> is used as the representation of the value 1,

the second <a>counter symbol</a> (if it exists) is used as the representation of the value 2, etc.

If the system is ''cyclic'',

the '@counter-style/symbols' descriptor must contain at least one <a>counter symbol</a>.

This system is defined over all counter values.

<div class=example>

A "triangle bullet" counter style can be defined as:

<pre>

@counter-style <dfn noexport>triangle</dfn> {

system: cyclic;

symbols: ‣;

suffix: " ";

}

</pre>

It will then produce lists that look like:

<pre>

‣ One

‣ Two

‣ Three

</pre>

</div>

If there are <var>N</var> <a>counter symbols</a>

and a representation is being constructed for the integer <var>value</var>,

the representation is the <a>counter symbol</a>

at index ( (<var>value</var>-1) mod <var>N</var>)

of the list of <a>counter symbols</a> (0-indexed).

<!--

████████ ████ ██ ██ ████████ ████████

██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██

██████ ██ ███ ██████ ██ ██

██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██

██ ████ ██ ██ ████████ ████████

-->

<h4 id="fixed-system">

Exhaustible Symbols: the ''system/fixed'' system</h4>

The <dfn value for="@counter-style/system">fixed</dfn> counter system runs through its list of counter symbols once,

then falls back.

It is useful for representing counter styles that only have a finite number of representations.

For example, Unicode defines several limited-length runs of special characters meant for lists,

such as circled digits.

If the system is ''system/fixed'',

the '@counter-style/symbols' descriptor must contain at least one <a>counter symbol</a>.

This system is defined over counter values in a finite range,

starting with the <a>first symbol value</a> and having a length equal to the length of the list of <a>counter symbols</a>.

When this system is specified,

it may optionally have an integer provided after it,

which sets the <dfn export>first symbol value</dfn>.

If it is omitted, the <a>first symbol value</a> is 1.

<div class=example>

A "box-corner" counter style can be defined as:

<pre>

@counter-style <dfn noexport>box-corner</dfn> {

system: fixed;

symbols: ◰ ◳ ◲ ◱;

suffix: ': ';

}

</pre>

It will then produce lists that look like:

<pre>

◰: One

◳: Two

◲: Three

◱: Four

5: Five

6: Six

</pre>

</div>

The first <a>counter symbol</a> is the representation for the <a>first symbol value</a>,

and subsequent counter values are represented by subsequent <a>counter symbols</a>.

Once the list of <a>counter symbols</a> is exhausted,

further values cannot be represented by this counter style,

and must instead be represented by the fallback counter style.

<!--

██████ ██ ██ ██ ██ ████████ ███████ ██ ████ ██████

██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ██ ██ ██

██ ████ ████ ████ ██ ██ ██ ██ ██ ██ ██

██████ ██ ██ ███ ██ ████████ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██████ ██ ██ ██ ████████ ███████ ████████ ████ ██████

-->

<h4 id="symbolic-system">

Repeating Symbols: the ''symbolic'' system</h4>

The <dfn value for="system">symbolic</dfn> counter system cycles repeatedly through its provided symbols,

doubling, tripling, etc. the symbols on each successive pass through the list.

For example, if the original symbols were "*" and "†",

then on the second pass they would instead be "**" and "††",

while on the third they would be "***"and "†††", etc.

It can be used for footnote-style markers,

and is also sometimes used for alphabetic-style lists for a slightly different presentation than what the ''system/alphabetic'' system presents.

If the system is ''symbolic'',

the '@counter-style/symbols' descriptor must contain at least one <a>counter symbol</a>.

This system is defined only over strictly positive counter values.

<div class=example>

An "footnote" counter style can be defined as:

<pre>

@counter-style <dfn noexport>footnote</dfn> {

system: symbolic;

symbols: '*' ⁑ † ‡;

suffix: " ";

}

</pre>

It will then produce lists that look like:

<pre>

* One

⁑ Two

† Three

‡ Four

** Five

⁑⁑ Six

</pre>

</div>

<div class=example>

Some style guides mandate a list numbering that looks similar to ''upper-alpha'',

but repeats differently after the first 26 values,

instead going "AA", "BB", "CC", etc.

This can be achieved with the symbolic system:

<pre>

@counter-style <dfn noexport>upper-alpha-legal</dfn> {

system: symbolic;

symbols: A B C D E F G H I J K L M

N O P Q R S T U V W X Y Z;

}

</pre>

This style is identical to ''upper-alpha'' through the first 27 values,

but they diverge after that, with ''upper-alpha'' going "AB", "AC", "AD", etc.

Starting at the 53rd value, ''upper-alpha'' goes "BA", "BB", "BC", etc.,

while this style jumps into triple digits with "AAA", "BBB", "CCC", etc.

</div>

To construct the representation, run the following algorithm:

Let <var>N</var> be the length of the list of <a>counter symbols</a>,

<var>value</var> initially be the counter value,

<var>S</var> initially be the empty string,

and <var>symbol(n)</var> be the nth <a>counter symbol</a> in the list of <a>counter symbols</a> (0-indexed).

<ol>

<li>Let the <var>chosen symbol</var> be <code class='inline'>symbol( (<var>value</var> - 1) mod <var>N</var>)</code>.

<li>Let the <var>representation length</var> be <code class='inline'>ceil( <var>value</var> / <var>N</var> )</code>.

<li>Append the <var>chosen symbol</var> to <var>S</var> a number of times equal to the <var>representation length</var>.

</ol>

Finally, return <var>S</var>.

<!--

███ ██ ████████ ██ ██ ███ ████████ ████████ ████████ ████ ██████

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ████████ █████████ ██ ██ ████████ ██████ ██ ██ ██

█████████ ██ ██ ██ ██ █████████ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ████████ ██ ██ ██ ██ ██ ████████ ████████ ██ ████ ██████

-->

<h4 id="alphabetic-system">

Bijective Numerals: the ''alphabetic'' system</h4>

The <dfn value for="@counter-style/system">alphabetic</dfn> counter system interprets the list of <a>counter symbols</a> as digits to an <em>alphabetic</em> numbering system,

similar to the default ''lower-alpha'' counter style,

which wraps from "a", "b", "c", to "aa", "ab", "ac".

Alphabetic numbering systems do not contain a digit representing 0;

so the first value when a new digit is added is composed solely of the first digit.

Alphabetic numbering systems are commonly used for lists,

and also appear in many spreadsheet programs to number columns.

The first <a>counter symbol</a> in the list is interpreted as the digit 1,

the second as the digit 2,

and so on.

If the system is ''system/alphabetic'',

the '@counter-style/symbols' descriptor must contain at least two <a>counter symbols</a>.

This system is defined only over strictly positive counter values.

<div class=example>

A counter style using go stones can be defined as:

<pre>

@counter-style <dfn noexport>go</dfn> {

system: alphabetic;

symbols: url(white.svg) url(black.svg);

suffix: " ";

}

</pre>

It will then produce lists that look like:

<div class='alphabetic-example'>

<span><img src=images/white.svg width=16 height=16 alt=""></span> One<br>

<span><img src=images/black.svg width=16 height=16 alt=""></span> Two<br>

<span><img src=images/white.svg width=16 height=16 alt=""><img src=images/white.svg width=16 height=16 alt=""></span> Three<br>

<span><img src=images/white.svg width=16 height=16 alt=""><img src=images/black.svg width=16 height=16 alt=""></span> Four<br>

<span><img src=images/black.svg width=16 height=16 alt=""><img src=images/white.svg width=16 height=16 alt=""></span> Five<br>

<span><img src=images/black.svg width=16 height=16 alt=""><img src=images/black.svg width=16 height=16 alt=""></span> Six<br>

<span><img src=images/white.svg width=16 height=16 alt=""><img src=images/white.svg width=16 height=16 alt=""><img src=images/white.svg width=16 height=16 alt=""></span> Seven

</div>

Note: This example requires support for SVG images to display correctly.

</div>

If there are <var>N</var> <a>counter symbols</a>,

the representation is a base <var>N</var> alphabetic number using the <a>counter symbols</a> as digits.

To construct the representation, run the following algorithm:

Let <var>N</var> be the length of the list of <a>counter symbols</a>,

<var>value</var> initially be the counter value,

<var>S</var> initially be the empty string,

and <var>symbol(n)</var> be the nth <a>counter symbol</a> in the list of <a>counter symbols</a> (0-indexed).

While <var>value</var> is not equal to 0:

<ol>

<li>Set <var>value</var> to <code><var>value</var> - 1</code>.

<li>Prepend <var>symbol( <var>value</var> mod <var>N</var> )</var>

to <var>S</var>.

<li>Set <var>value</var> to <code>floor( <var>value</var> / <var>N</var> )</code>.

</ol>

Finally, return <var>S</var>.

<!--

██ ██ ██ ██ ██ ██ ████████ ████████ ████ ██████

███ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ██

████ ██ ██ ██ ████ ████ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ███ ██ ██████ ████████ ██ ██

██ ████ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ███████ ██ ██ ████████ ██ ██ ████ ██████

-->

<h4 id="numeric-system">

Positional Numerals: the ''numeric'' system</h4>

The <dfn value for="@counter-style/system">numeric</dfn> counter system interprets the list of <a>counter symbols</a>

as digits to a "place-value" numbering system,

similar to the default ''decimal'' counter style.

The first <a>counter symbol</a> in the list is interpreted as the digit 0,

the second as the digit 1,

and so on.

If the system is ''system/numeric'',

the '@counter-style/symbols' descriptor must contain at least two <a>counter symbols</a>.

This system is defined over all counter values.

<div class=example>

A "trinary" counter style can be defined as:

<pre>

@counter-style <dfn noexport>trinary</dfn> {

system: numeric;

symbols: '0' '1' '2';

}

</pre>

It will then produce lists that look like:

<pre>

1. One

2. Two

10. Three

11. Four

12. Five

20. Six

</pre>

</div>

If there are <var>N</var> <a>counter symbols</a>,

the representation is a base <var>N</var> number using the <a>counter symbols</a> as digits.

To construct the representation, run the following algorithm:

Let <var>N</var> be the length of the list of <a>counter symbols</a>,

<var>value</var> initially be the counter value,

<var>S</var> initially be the empty string,

and <var>symbol(n)</var> be the nth <a>counter symbol</a> in the list of <a>counter symbols</a> (0-indexed).

<ol>

<li>If <var>value</var> is 0, append <code>symbol(0)</code> to

<var>S</var> and return <var>S</var>.

<li>While <var>value</var> is not equal to 0:

<ol>

<li>Prepend <var>symbol( <var>value</var> mod <var>N</var> )</var>

to <var>S</var>.

<li>Set <var>value</var> to <code>floor( <var>value</var> / <var>N</var> )</code>.

</ol>

<li>Return <var>S</var>.

</ol>

<!--

███ ████████ ████████ ████ ████████ ████ ██ ██ ████████

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██████

█████████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ████████ ████████ ████ ██ ████ ███ ████████

-->

<h4 id="additive-system">

Accumulating Numerals: the ''additive'' system</h4>

The <dfn value for="@counter-style/system">additive</dfn> counter system is used to represent "sign-value" numbering systems,

which, rather than reusing digits in different positions to change their value,

define additional digits with much larger values,

so that the value of the number can be obtained by adding all the digits together.

This is used in Roman numerals

and other numbering systems around the world.

If the system is ''additive'',

the '@counter-style/additive-symbols' descriptor must contain at least one <a>additive tuple</a>.

This system is nominally defined over all counter values

(see algorithm, below, for exact details).

<div class=example>

A "dice" counter style can be defined as:

<pre>

@counter-style <dfn noexport>dice</dfn> {

system: additive;

additive-symbols: 6 ⚅, 5 ⚄, 4 ⚃, 3 ⚂, 2 ⚁, 1 ⚀;

suffix: " ";

}

</pre>

It will then produce lists that look like:

<pre>

⚀ One

⚁ Two

⚂ Three

...

⚅⚄ Eleven

⚅⚅ Twelve

⚅⚅⚀ Thirteen

</pre>

</div>

<div algorithm="additive representation">

To construct the representation:

1. Let |value| initially be the counter value,

|S| initially be the empty string,

and |symbol list| initially be the list of <a>additive tuples</a>.

2. If |value| is zero:

1. If |symbol list| contains a tuple with a weight of zero,

append that tuple's <a>counter symbol</a> to |S| and return |S|.

2. Otherwise, the given counter value cannot be represented by this counter style,

and must instead be represented by the fallback counter style.

3. For each |tuple| in |symbol list|:

1. Let |symbol| and |weight| be |tuple|'s [=counter symbol=] and weight, respectively.

2. If |weight| is zero, or |weight| is greater than |value|,

[=iteration/continue=].

3. Let |reps| be <code>floor( |value| / |weight| )</code>.

4. Append |symbol| to |S| |reps| times.

5. Decrement |value| by <code>|weight| * |reps|</code>.

6. If |value| is zero, return |S|.

4. Assertion: |value| is still non-zero.

The given counter value cannot be represented by this counter style,

and must instead be represented by the fallback counter style.

</div>

Note: All of the predefined additive ''@counter-style'' rules in this specification

produce representations for every value in their range,

but it's possible to produce values for ''@counter-style/additive-symbols'' that will fail to find a representation

with the algorithm defined above,

even though theoretically a representation could be found.

For example, if a ''@counter-style'' was defined with ''additive-symbols: 3 "a", 2 "b";'',

the algorithm defined above will fail to find a representation for a counter value of 4,

even though theoretically a "bb" representation would work.

While unfortunate, this is required to maintain the property that the algorithm runs in linear time

relative to the size of the counter value.

<!--

████████ ██ ██ ████████ ████████ ██ ██ ████████ ██████

██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ████ ██ ██ ██ ██

██████ ███ ██ ██████ ██ ██ ██ ██ ██ ██████

██ ██ ██ ██ ██ ██ ████ ██ ██ ██

██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██

████████ ██ ██ ██ ████████ ██ ██ ████████ ██████

-->

<h4 id="extends-system">

Building from Existing Counter Styles: the ''extends'' system

<span id='override-system'></span></h4>

The <dfn value for="@counter-style/system">extends</dfn> system allows an author to use the algorithm of another counter style,

but alter other aspects,

such as the negative sign or the suffix.

If a counter style uses the ''extends'' system,

any unspecified descriptors must be taken from the extended counter style specified,

rather than taking their initial values.

If a ''@counter-style'' uses the ''extends'' system,

it must not contain a '@counter-style/symbols' or '@counter-style/additive-symbols' descriptor,

or else the ''@counter-style'' rule is invalid.

If the specified <<counter-style-name>> is an [=ASCII case-insensitive=] match

for ''disc'', ''circle'', ''square'', ''disclosure-open'', or ''disclosure-closed''

(any of the predefined symbolic counter styles),

using ''extend'' extends from the “standard” definition of the rules

provided in the normative stylesheet

(rather than the exception allowing them to be drawn in a different, user-agent-specific fashion.)

If the specified counter style name isn't the name of any defined counter style,

it must be treated as if it was extending the ''decimal'' counter style.

If one or more ''@counter-style'' rules form a cycle with their ''extends'' values,

all of the counter styles participating in the cycle

must be treated as if they were extending the ''decimal'' counter style instead.

<div class='example'>

For example, if you wanted a counter style that was identical to decimal,

but used a parenthesis rather than a period after it, like:

<pre>

1) first item

2) second item

3) third item

</pre>

Rather than writing up an entirely new counter style,

this can be done by just extending ''decimal'':

<pre>

@counter-style decimal-paren {

system: extends decimal;

suffix: ") ";

}

</pre>

</div>

<!--

██ ██ ████████ ██████ ███ ████████ ████ ██ ██ ████████

███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██████ ██ ████ ██ ██ ██ ██ ██ ██ ██████

██ ████ ██ ██ ██ █████████ ██ ██ ██ ██ ██

██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ████████ ██████ ██ ██ ██ ████ ███ ████████

-->

<h3 id='counter-style-negative'>

Formatting negative values: the '@counter-style/negative' descriptor</h3>

<pre class='descdef'>

Name: negative

For: @counter-style

Value: <<symbol>> <<symbol>>?

Initial: "-"

</pre>

The '@counter-style/negative' descriptor defines how to alter the representation when

the counter value is negative.

The first <<symbol>> in the value is prepended to the representation when the

counter value is negative. The second <<symbol>>, if specified, is appended

to the representation when the counter value is negative.

<div class='example'>

For example, specifying ''negative: "(" ")";'' will make negative

values be wrapped in parentheses, which is sometimes used in financial

contexts, like "(2) (1) 0 1 2 3...".

</div>

Not all '@counter-style/system' values use a negative sign.

In particular, a counter style <dfn export lt="use a negative sign|uses a negative sign">uses a negative sign</dfn>

if its '@counter-style/system' value is

''symbolic'',

''system/alphabetic'',

''system/numeric'',

''additive'',

or ''extends'' if the extended counter style itself <a>uses a negative sign</a>.

If a counter style does not <a>use a negative sign</a>,

it ignores the negative sign when <a lt="generate a counter representation">generating a counter representation</a>.

<!--

████████ ████████ ████████ ████████ ████ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██

████████ ████████ ██████ ██████ ██ ███

██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ████████ ██ ████ ██ ██

-->

<h3 id='counter-style-prefix'>

Symbols before the marker: the '@counter-style/prefix' descriptor</h3>

<pre class='descdef'>

Name: prefix

For: @counter-style

Value: <<symbol>>

Initial: ""

</pre>

The '@counter-style/prefix' descriptor specifies a <<symbol>>

that is prepended to the marker representation.

Prefixes come before any negative sign.

Note: Prefixes are only added by the algorithm for constructing

the default contents of the ''::marker'' pseudo-element; the prefix is not

added automatically when the ''counter()'' or ''counters()'' functions are used.

<!--

██████ ██ ██ ████████ ████████ ████ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██

██████ ██ ██ ██████ ██████ ██ ███

██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██

██████ ███████ ██ ██ ████ ██ ██

-->

<h3 id='counter-style-suffix'>

Symbols after the marker: the '@counter-style/suffix' descriptor</h3>

<pre class='descdef'>

Name: suffix

For: @counter-style

Value: <<symbol>>

Initial: ". "

</pre>

The '@counter-style/suffix' descriptor specifies a <<symbol>>

that is appended to the marker representation.

Suffixes are added to the representation after negative signs.

Note: Suffixes are only added by the algorithm for constructing

the default contents of the ''::marker'' pseudo-element; the suffix is not

added automatically when the counter() or counters() functions are used.

<!--

████████ ███ ██ ██ ██████ ████████

██ ██ ██ ██ ███ ██ ██ ██ ██

██ ██ ██ ██ ████ ██ ██ ██

████████ ██ ██ ██ ██ ██ ██ ████ ██████

██ ██ █████████ ██ ████ ██ ██ ██

██ ██ ██ ██ ██ ███ ██ ██ ██

██ ██ ██ ██ ██ ██ ██████ ████████

-->

<h3 id='counter-style-range'>

Limiting the counter scope: the '@counter-style/range' descriptor</h3>

<pre class='descdef'>

Name: range

For: @counter-style

Value: [ [ <<integer>> | infinite ]{2} ]# | auto

Initial: auto

</pre>

The '@counter-style/range' descriptor defines the ranges over which the counter style is defined.

If a counter style is used to represent a counter value outside of its ranges,

the counter style instead drops down to its fallback counter style.

<dl dfn-for="@counter-style/range">

<dt><dfn value>auto</dfn>

<dd>

The range depends on the counter system:

<ul>

<li>

For ''cyclic'', ''system/numeric'', and ''system/fixed'' systems,

the range is negative infinity to positive infinity.

<li>

For ''system/alphabetic'' and ''symbolic'' systems,

the range is 1 to positive infinity.

<li>

For ''additive'' systems,

the range is 0 to positive infinity.

<li>

For ''extends'' systems,

the range is whatever ''range/auto'' would produce for the extended system;

if extending a complex predefined style (<a section href="#complex-predefined-counters"></a>),

the range is the style's defined range.

</ul>

<dt>[ [ <<integer>> | infinite ]{2} ]#

<dd>

This defines a comma-separated list of ranges.

For each individual range,

the first value is the lower bound

and the second value is the upper bound.

This range is inclusive - it contains both the lower and upper bound numbers.

If ''range/infinite'' is used as the first value in a range,

it represents negative infinity;

if used as the second value,

it represents positive infinity.

The range of the counter style is the union of all the ranges defined in the list.

If the lower bound of any range is higher than the upper bound,

the entire descriptor is invalid and must be ignored.

</dl>

Implementations must support ranges with a lower bound of at least -2¹⁵

and an upper bound of at least 2¹⁵-1

(the range of a signed 2-byte int).

They may support higher ranges.

If any specified bound is outside of the implementation's supported bounds,

it must be treated as the closest bound that the implementation does support.

<!--

████████ ███ ████████

██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██

████████ ██ ██ ██ ██

██ █████████ ██ ██

██ ██ ██ ██ ██

██ ██ ██ ████████

-->

<h3 id='counter-style-pad'>

Zero-Padding and Constant-Width Representations: the '@counter-style/pad' descriptor</h3>

<pre class='descdef'>

Name: pad

For: @counter-style

Value: <<integer [0,&infin;]>> && <<symbol>>

Initial: 0 ""

</pre>

The '@counter-style/pad' descriptor allows an author to specify a "fixed-width" counter style,

where representations shorter than the pad value are padded with a particular <<symbol>>.

Representations larger than the specified pad value are constructed as normal.

<dl>

<dt><<integer [0,&infin;]>> &amp;&amp; <<symbol>>

<dd>

The <<integer>> specifies a minimum length that all counter representations must reach.

Let <var>difference</var> be the provided <<integer>>

minus the number of <a>grapheme clusters</a> in the <a>initial representation for the counter value</a>.

<span class='note'>(Note that, per the algorithm to <a>generate a counter representation</a>,

this occurs before adding prefixes/suffixes/negatives.)</span>

If the counter value is negative

and the counter style <a>uses a negative sign</a>,

further reduce <var>difference</var>

by the number of <a>grapheme clusters</a> in the counter style’s '@counter-style/negative' descriptor’s <<symbol>>(s).

If <var>difference</var> is greater than zero,

prepend <var>difference</var> copies of the specified <<symbol>> to the representation.

Negative <<integer>> values are not allowed.

</dl>

<div class='example'>

The most common example of "fixed-width" numbering is zero-padded decimal numbering.

If an author knows that the numbers used will be less than a thousand, for example,

it can be zero-padded with a simple ''pad: 3 "0";'' descriptor,

ensuring that all of the representations are 3 digits wide.

This will cause, for example,

1 to be represented as "001",

20 to be represented as "020",

300 to be represented as "300",

4000 to be represented as "4000",

and -5 to be represented as "-05".

</div>

Note: The '@counter-style/pad' descriptor counts the number of <a>grapheme clusters</a> in the representation,

but pads it with <<symbol>>s.

If the specified '@counter-style/pad' <<symbol>> is multi-character,

this will likely not have the desired effect.

Unfortunately, there's no way to use the number of <a>grapheme clusters</a> in the '@counter-style/pad' <<symbol>>

without violating useful constraints.

It is recommended that authors only specify <<symbol>>s of a single <a>grapheme cluster</a>

in the '@counter-style/pad' descriptor.

<!--

████████ ███ ██ ██ ████████ ███ ██████ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██████ ██ ██ ██ ██ ████████ ██ ██ ██ █████

██ █████████ ██ ██ ██ ██ █████████ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ████████ ████████ ████████ ██ ██ ██████ ██ ██

-->

<h3 id='counter-style-fallback'>