Is there a detailed documentation on token types/styles?

I was about to start writing a new mode, but couldn’t find in documentation answers to two questions:

  1. What are the recognized values for token styles?
  2. Which one I need to return for a given language token?

Question 1 is partially answered by a list of CSS rules in codemirror.css. Only partially because CSS rules hardly pass for a definitive list of semantic options.

As for question 2, for some token types it’s pretty straightforward, e.g. I can easily infer what should be marked as string, number or keyword. For others - it’s very ambiguous or even not obvious at all: what kinds of brackets qualify for bracket. What is variable-2 and how it’s different from variable? variable-3?? What’s def supposed to be?

Could someone please point me to a relevant documentation?

There’s no real prescribed way to do this—every mode pretty much does its own thing, depending on what kind of tokens it needs. def is a variable definition, numbered things like variable-2 and string-2 are a way to indicate that something is a special kind of variable or string (say a local variable or a template string or whatever your language defines).

I’m trying to be a bit more rigorous about this in the upcoming CodeMirror 6, but for version 5, the advice is to just do what works for your mode.