Module highlights 

Highlight category definitions - single source of truth.

This module defines all highlight categories used for syntax highlighting. It maps the large vocabulary of capture names from various sources (nvim-treesitter, helix, etc.) to a small set of theme slots.

Architecture

The highlighting system has three layers:

1. Capture names - The broad vocabulary used in highlight queries (e.g., @keyword.function, @include, @conditional, @repeat)

2. Theme slots - A fixed set of ~15-20 color slots that themes define (e.g., keyword, function, string, comment, type)

3. HTML tags - Short tags for rendering (e.g., <a-k>, <a-f>, <a-s>)

Multiple capture names map to the same theme slot. For example:

• include, keyword.import, keyword.require → all use the keyword slot
• conditional, keyword.conditional, repeat → all use the keyword slot

Adjacent spans that map to the same slot are coalesced into a single HTML element.

Structs

HighlightDef

A highlight category definition.

Enums

ThemeSlot

The theme slots - the fixed set of color categories that themes define. This is the final destination for all capture names.

Constants

CAPTURE_NAMES

The complete list of capture names that arborium recognizes.

COUNT

Total number of highlight categories.

HIGHLIGHTS

All highlight categories, in order. The index in this array is the highlight index used throughout the codebase.

Functions

capture_to_slot

Map any capture name to its theme slot.

css_inheritance_rules

Generate CSS inheritance rules for sub-categories. Returns rules like “a-kc, a-kf, a-ki { color: inherit; }” grouped by parent.

names

Get the highlight names array for tree-sitter configuration.

parent_tag

Get the parent tag for inheritance, if any.

prefixed_tag

Get the prefixed HTML tag (e.g., “a-kf”) for a highlight index.

slot_to_highlight_index

Map a theme slot to a canonical highlight index.

tag

Get the HTML tag suffix for a highlight index. Returns None for indices that should produce no styling (like “none” or “nospell”).

tag_for_capture

Get the HTML tag for a capture name directly.

tag_to_name

Map a short tag to its full name.