CSS modules: Symbols descriptor and function

files/en-us/web/css/@counter-style/symbols/index.md

@@ -7,37 +7,37 @@ browser-compat: css.at-rules.counter-style.symbols
 
 {{CSSRef}}
 
-The **`symbols`** [CSS](/en-US/docs/Web/CSS) descriptor is used to specify the symbols that the specified counter system will use to construct counter representations.
+The **`symbols`** [CSS](/en-US/docs/Web/CSS) descriptor of the {{cssxref("@counter-style")}} at-rule is used to specify the symbols for creating counter representations in the specified counter system. Specifying this descriptor is mandatory when the value of the {{cssxref('@counter-style/system', 'system')}} descriptor is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`.
 
 ## Syntax
 
-The `symbols` descriptor is specified as one or more `<symbol>`s.
+```css
+symbols: A B C D E;
+symbols: "\24B6" "\24B7" "\24B8" D E;
+symbols: "0" "1" "2" "4" "5" "6" "7" "8" "9";
+symbols: url("one.svg") url("two.svg") url("three.svg");
+symbols: indic-numbers;
+```
 
 ### Values
 
+The `symbols` descriptor is specified as a list one or more space-separated `<symbol>` values.
+
 - `<symbol>`
 
-  - : Represents a symbol used within the counter system. This must be one of the following data types:
+  - : Specifies the symbol to use within the counter system. Each symbol in the list can be either a {{cssxref("&lt;string&gt;")}}, an {{cssxref("&lt;image&gt;")}}, or a {{cssxref("&lt;custom-ident&gt;")}}. The `<image>` value can, in turn, be specified as a {{cssxref("&lt;url&gt;")}} or {{cssxref("&lt;gradient&gt;")}}.
 
-    - {{cssxref("&lt;string&gt;")}}
-    - {{cssxref("&lt;image&gt;")}} (Note: This value is "at risk" and may be removed from the specification. It is not yet implemented.)
-    - {{cssxref("&lt;custom-ident&gt;")}}
+  > **Note:** When using an {{glossary("identifier")}} for a symbol, note that {{glossary("ASCII")}} non-letters such as `*`, `"`, and `\` are not considered identifiers. They must be either quoted as a string or escaped.
 
 ## Description
 
 A symbol can be a string, image, or identifier. It is used within the {{cssxref("@counter-style")}} [at-rule](/en-US/docs/Web/CSS/At-rule).
 
-```css
-symbols: A B C D E;
-symbols: "\24B6" "\24B7" "\24B8" D E;
-symbols: "0" "1" "2" "4" "5" "6" "7" "8" "9";
-symbols: url("one.svg") url("two.svg") url("three.svg");
-symbols: indic-numbers;
-```
+When the value of the {{cssxref('@counter-style/system', 'system')}} descriptor is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`, the `symbols` descriptor must be specified. For the `additive` system, use the {{cssxref('@counter-style/additive-symbols', 'additive-symbols')}} descriptor instead to specify the symbols.
 
-The `symbols` descriptor must be specified when the value of the {{cssxref('@counter-style/system', 'system')}} descriptor is `cyclic`, `numeric`, `alphabetic`, `symbolic`, or `fixed`. When the `additive` system is used, use the {{cssxref('@counter-style/additive-symbols', 'additive-symbols')}} descriptor instead to specify the symbols.
+While a space between quoted symbols is not required, it makes CSS more readable. To use a quote as a symbol, either escape the quote character or enclose the character within different quotes, such as `"'"`.
 
-While a space between quoted symbols is not required, it makes the CSS more legible. To use a quote as a symbol, either escape the quote character or enclose the character is using different quotes, such as `"'"`.
+When defining symbols with identifiers instead of strings, be sure to use identifier syntax rules. For example, as noted above, ASCII non-letters such as `*` are not identifiers and must be either quoted or escaped. Hex escape characters are followed by a space. This space may look like the space separating two identifiers, but it enables digits to follow hex-escaped characters. This means that two spaces must be included after a hex-escaped identifier to separate it from the next identifier. For example, it is better to use the string `"\2A 1"` instead of `\2A  1` with two spaces, as your code tools might remove double spaces. It is generally safer to quote identifiers that need to be escaped or use strings.
 
 ## Formal definition
 
@@ -51,6 +51,8 @@ While a space between quoted symbols is not required, it makes the CSS more legi
 
 ### Setting counter symbols
 
+In this example, the list of values for the `symbols` descriptor include letters (`A`, `D`, `E`), a number within quotes (`"1"`), and a hex-escape identifier within quotes (`"\24B7"`) for the character `Ⓑ`.
+
 #### HTML
 
 ```html
@@ -90,8 +92,8 @@ While a space between quoted symbols is not required, it makes the CSS more legi
 
 ## See also
 
-- The `symbols` descriptor is used within the {{cssxref("@counter-style")}} at-rule.
-- {{Cssxref("list-style")}}, {{Cssxref("list-style-image")}}, {{Cssxref("list-style-position")}}
-- {{cssxref("symbols", "symbols()")}}, the functional notation creating anonymous counter styles
+- {{cssxref("@counter-style")}} descriptors: {{cssxref("@counter-style/system","system")}}, {{cssxref("@counter-style/additive-symbols", "additive-symbols")}}, {{cssxref("@counter-style/negative", "negative")}}, {{cssxref("@counter-style/prefix", "prefix")}}, {{cssxref("@counter-style/suffix", "suffix")}}, {{cssxref("@counter-style/range", "range")}}, {{cssxref("@counter-style/pad", "pad")}}, {{cssxref("@counter-style/speak-as", "speak-as")}}, {{cssxref("@counter-style/fallback", "fallback")}}
+- List style properties: {{cssxref("list-style")}}, {{cssxref("list-style-image")}}, {{cssxref("list-style-position")}}
+- {{cssxref("symbols", "symbols()")}} function
 - {{cssxref("url", "url()")}} function
 - [CSS counter styles](/en-US/docs/Web/CSS/CSS_counter_styles) module

files/en-us/web/css/symbols/index.md

@@ -7,7 +7,9 @@ browser-compat: css.properties.list-style-type.symbols
 
 {{CSSRef}}
 
-The **`symbols()`** CSS function lets you define counter styles inline, directly as the value of a property such as {{cssxref("list-style")}}. Unlike {{cssxref("@counter-style")}}, `symbols()` is _anonymous_ (i.e., it can only be used once). Although less powerful, it is shorter and easier to write than {{cssxref("@counter-style")}}.
+The **`symbols()`** CSS function enables defining counter styles inline, directly as a value of properties such as {{cssxref("list-style")}}, providing a less powerful but simpler alternative to the {{cssxref("@counter-style")}} method of defining a counter style.
+
+Unlike {{cssxref("@counter-style")}}, which defines a reusable counter style, `symbols()` is _anonymous_ (i.e., it can only be used once). This function accepts strings and images as values. In comparison, the {{cssxref("@counter-style")}}'s [`symbols`](/en-US/docs/Web/CSS/@counter-style/symbols) descriptor also accepts identifiers.
 
 ## Syntax
 
@@ -59,5 +61,7 @@ ol {
 
 ## See also
 
-- {{cssxref("@counter-style")}}
-- {{cssxref("list-style-type")}} and the corresponding shorthand {{cssxref("list-style")}}.
+- {{cssxref("@counter-style")}} descriptors: {{cssxref("@counter-style/system","system")}}, {{cssxref("@counter-style/symbols", "symbols")}}, {{cssxref("@counter-style/additive-symbols", "additive-symbols")}}, {{cssxref("@counter-style/prefix", "prefix")}}, {{cssxref("@counter-style/suffix", "suffix")}}, {{cssxref("@counter-style/range", "range")}}, {{cssxref("@counter-style/pad", "pad")}}, {{cssxref("@counter-style/speak-as", "speak-as")}}, {{cssxref("@counter-style/fallback", "fallback")}}
+- List style properties: {{cssxref("list-style")}}, {{cssxref("list-style-type")}}
+- [CSS counter styles](/en-US/docs/Web/CSS/CSS_counter_styles) module
+- [CSS lists and counters](/en-US/docs/Web/CSS/CSS_lists) module