How to Inspect and Debug CSS @counter-style Custom Numbering in Safari Web Inspector

In standard web typography, formatting ordered lists (<ol>) or generated section numbering has traditionally been constrained to browser-provided keyword list styles (such as decimal, lower-roman, lower-alpha, or disc). When a design system called for bespoke numbering systems—such as circled digits, legal outline clauses, Roman numerals beyond standard ranges, or custom glyph suffixes—developers were forced to hide native list markers and reconstruct complex counters using counter-reset, counter-increment, and ::before pseudo-elements. The CSS Counter Styles Level 3 specification resolves this natively through the @counter-style at-rule. Supported across modern WebKit and Safari, developers can inspect, test, and debug custom counter systems directly in Safari Web Inspector.

Architecture of the CSS @counter-style At-Rule

The @counter-style rule defines a custom counter algorithm that can be assigned directly to list-style-type or referenced within counter() functions. The rule is composed of core descriptors:

• system: Defines the algorithm used to translate integer counter values into string representations. Common systems include:
  • numeric: Standard positional base system (like binary, octal, or decimal).
  • alphabetic: Positional numbering without a zero symbol (like spreadsheet columns: A, B… Z, AA, AB).
  • symbolic: Repeats symbols successively (such as footnote asterisks: *, **, ***).
  • cyclic: Cycles continuously through a fixed sequence of symbols.
  • fixed: Applies symbols to specific fixed integers, falling back if exceeded.
• symbols: The list of strings, glyphs, or emojis used by the numbering algorithm.
• prefix / suffix: Text appended before or after the marker (default suffix is ". ").
• pad: Specifies minimum marker width with padding characters (e.g. zero-padded numbers: pad: 2 "0").
• fallback: The secondary counter style applied if the counter value falls outside the specified range.

Defining Custom Counter Styles in Modern CSS

To define a custom circled numeric counter style and apply it to an ordered list:

/* Define a custom circled digit counter style */
@counter-style circled-numbers {
    system: fixed;
    symbols: ➀ ➁ ➂ ➃ ➄ ➅ ➆ ➇ ➈ ➉;
    suffix: " ";
    fallback: decimal;
}

/* Apply the custom style to list elements */
ol.custom-timeline {
    list-style-type: circled-numbers;
    padding-left: 1.5rem;
}

For values 1 through 10, Safari renders native circled glyphs. If the list extends to 11, the rule gracefully falls back to standard decimal numbering as defined in the fallback descriptor.

Creating Pad and Zero-Indexed Counter Styles

For technical documentation, code listings, or index registers requiring uniform two-digit numbering:

@counter-style padded-decimal {
    system: numeric;
    symbols: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9";
    pad: 2 "0";
    suffix: ") ";
}

ol.spec-list {
    list-style-type: padded-decimal;
}

This automatically produces 01), 02)… 09), 10) markers with native marker positioning.

Inspecting @counter-style in Safari Web Inspector

To inspect custom counter style definitions in Safari Web Inspector:

1. Launch Safari and navigate to your web project.
2. Right-click the styled list item (<li>) and choose Inspect Element.
3. In the DOM tree, locate the pseudo-element ::marker under the selected list item.
4. In the right-hand inspection sidebar, select the Styles tab. Locate the list-style-type declaration.
5. Scroll through the stylesheet rules to verify that Safari parsed the @counter-style block without syntax errors or invalid descriptor flags.

Debugging Marker Alignment and Spacing

When custom markers introduce wide Unicode characters or custom prefixes, default list indentation can cause markers to clip outside the viewport. In Safari Web Inspector:

1. Select the ::marker pseudo-element in the Elements tree.
2. In the Styles pane, inspect custom styling applied to the marker itself (such as color, font-size, or font-family).
3. If markers clip against the left margin, adjust padding-left on the parent <ol> or configure list-style-position: inside to keep the custom symbol within the content box.

Testing Fallback Behavior and Range Boundaries

To ensure your counter system behaves reliably when lists grow unexpectedly large:

1. In the Safari Web Inspector DOM tree, edit a list item’s value attribute dynamically (e.g. <li value="15">).
2. Observe whether Safari correctly switches to the configured fallback style when the value exceeds the range or fixed symbol table.
3. Verify that the transition from custom glyphs to fallback decimal numbers renders without layout shifts or missing marker boxes.