Skip to content

Commit b4dc20a

Browse files
respencer-nclclaude
respencer-ncl
and
claude
committed
Add Standard Highlighting reference page for RIDDL token colors
Documents the 11 Token types used across all RIDDL editors and their standard dark/light theme color mappings with hex codes, swatches, and platform implementation notes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b060d5e commit b4dc20a

4 files changed

Lines changed: 161 additions & 0 deletions

File tree

‎NOTEBOOK.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,19 @@ Documentation site is complete and deployed at https://ossum.tech.
66
All major sections are documented with proper RIDDL syntax
77
highlighting.
88

9+
**Completed (2026-02-14):**
10+
11+
- Added Standard Highlighting reference page
12+
(`docs/riddl/references/standard-highlighting.md`)
13+
- Documents the 11 `Token` enum types from the RIDDL compiler
14+
- Dark and light theme color tables with hex codes and swatches
15+
- Implementation notes for each platform (IntelliJ, VS Code,
16+
Synapify/ossum.ai Monaco, Pygments/MkDocs)
17+
- Design principles and guidance for new tool implementors
18+
- Colors sourced from Pygments lexer (`riddl_lexer/style.py`)
19+
and CSS overrides (`extra.css`) as canonical reference
20+
- Updated references index and mkdocs.yml nav
21+
922
**Completed (2026-02-13):**
1023

1124
- Rectified Reactive BBQ tutorial with verbatim riddl-models source

‎docs/riddl/references/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ user community. The current set of references are:
77
* [Cheat Sheet](cheat-sheet.md) - a dense, scannable reference for
88
every RIDDL definition type—what it means, when to use it, and
99
where it lives.
10+
* [Standard Highlighting](standard-highlighting.md) - the standard
11+
token types and color scheme used for RIDDL syntax highlighting
12+
across all editors and documentation tools.
1013
* [Language Reference](language-reference.md) - a detailed description
1114
of the structure and allowed syntax of RIDDL models.
1215
* [EBNF Grammar](ebnf-grammar.md) - a formal EBNF grammar for the

‎docs/riddl/references/standard-highlighting.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
description: >-
3+
Standard token types and color scheme used for RIDDL syntax
4+
highlighting across all editors and documentation tools.
5+
---
6+
7+
# Standard Highlighting
8+
9+
All RIDDL-aware tools—the IntelliJ plugin, VS Code extension,
10+
Synapify editor, ossum.ai playground, and this documentation
11+
site—share a common tokenization scheme for syntax highlighting.
12+
This page documents the standard token types and their associated
13+
colors.
14+
15+
## Token Types
16+
17+
The RIDDL lexer classifies every span of source text into one of
18+
eleven token types, defined in the compiler's AST:
19+
20+
```scala
21+
enum Token(at: At):
22+
case Punctuation(at: At)
23+
case QuotedString(at: At)
24+
case Readability(at: At)
25+
case Predefined(at: At)
26+
case Keyword(at: At)
27+
case Comment(at: At)
28+
case LiteralCode(at: At)
29+
case MarkdownLine(at: At)
30+
case Identifier(at: At)
31+
case Numeric(at: At)
32+
case Other(at: At)
33+
```
34+
35+
Each token type has a specific semantic meaning:
36+
37+
| Token Type | What It Covers | Examples |
38+
|------------|----------------|----------|
39+
| **Keyword** | Definition and statement keywords | `domain`, `context`, `entity`, `handler`, `send`, `tell` |
40+
| **Readability** | Connecting words that aid readability | `is`, `of`, `to`, `with`, `by`, `from` |
41+
| **Predefined** | Built-in type names | `String`, `Integer`, `UUID`, `Timestamp`, `Boolean` |
42+
| **Identifier** | User-defined names | `MyEntity`, `OrderPlaced`, `customerId` |
43+
| **QuotedString** | Double-quoted string literals | `"Hello world"`, `"application/json"` |
44+
| **Numeric** | Number literals | `42`, `3.14`, `100` |
45+
| **Punctuation** | Structural delimiters and operators | `{`, `}`, `(`, `)`, `,`, `:`, `=` |
46+
| **Comment** | Line and block comments | `// comment`, `/* block */` |
47+
| **MarkdownLine** | Pipe-prefixed documentation lines | `\|## Heading`, `\|Some description text` |
48+
| **LiteralCode** | Triple-quoted code blocks | ` ```scala ... ``` ` |
49+
| **Other** | Anything not classified above | Placeholder `???`, unrecognized text |
50+
51+
## Standard Color Scheme
52+
53+
The standard RIDDL color scheme uses a dark theme as the primary
54+
palette. Each implementation adapts these colors to its platform
55+
while preserving the semantic intent.
56+
57+
### Dark Theme
58+
59+
| Token Type | Color | Hex | Swatch |
60+
|------------|-------|-----|--------|
61+
| **Keyword** | Burnt orange | `#fa8b61` | <span style="background:#fa8b61;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#fa8b61</span> |
62+
| **Readability** | Yellow-olive | `#b3ae60` | <span style="background:#b3ae60;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#b3ae60</span> |
63+
| **Predefined** | Teal | `#19c4bf` | <span style="background:#19c4bf;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#19c4bf</span> |
64+
| **Identifier** | Light gray | `#a9b7c6` | <span style="background:#a9b7c6;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#a9b7c6</span> |
65+
| **QuotedString** | Bright green | `#98c379` | <span style="background:#98c379;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#98c379</span> |
66+
| **Numeric** | Steel blue | `#6897bb` | <span style="background:#6897bb;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#6897bb</span> |
67+
| **Punctuation** | Teal | `#0da19e` | <span style="background:#0da19e;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#0da19e</span> |
68+
| **Comment** | Gray *(italic)* | `#808080` | <span style="background:#808080;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#808080</span> |
69+
| **MarkdownLine** | Dim green *(italic)* | `#629755` | <span style="background:#629755;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#629755</span> |
70+
| **LiteralCode** | Dim green | `#629755` | <span style="background:#629755;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#629755</span> |
71+
| **Other** | Light gray | `#a9b7c6` | <span style="background:#a9b7c6;color:#000;padding:2px 12px;border-radius:3px;font-weight:bold">#a9b7c6</span> |
72+
73+
### Light Theme
74+
75+
| Token Type | Color | Hex | Swatch |
76+
|------------|-------|-----|--------|
77+
| **Keyword** | Dark orange | `#c75a20` | <span style="background:#c75a20;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#c75a20</span> |
78+
| **Readability** | Olive | `#7a7a30` | <span style="background:#7a7a30;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#7a7a30</span> |
79+
| **Predefined** | Teal | `#0d8a85` | <span style="background:#0d8a85;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#0d8a85</span> |
80+
| **Identifier** | Near black | `#2b2b2b` | <span style="background:#2b2b2b;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#2b2b2b</span> |
81+
| **QuotedString** | Forest green | `#50873a` | <span style="background:#50873a;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#50873a</span> |
82+
| **Numeric** | Muted blue | `#4a6a9a` | <span style="background:#4a6a9a;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#4a6a9a</span> |
83+
| **Punctuation** | Teal | `#0a7a75` | <span style="background:#0a7a75;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#0a7a75</span> |
84+
| **Comment** | Gray *(italic)* | `#707070` | <span style="background:#707070;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#707070</span> |
85+
| **MarkdownLine** | Dark green *(italic)* | `#3d6a30` | <span style="background:#3d6a30;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#3d6a30</span> |
86+
| **LiteralCode** | Dark green | `#3d6a30` | <span style="background:#3d6a30;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#3d6a30</span> |
87+
| **Other** | Near black | `#2b2b2b` | <span style="background:#2b2b2b;color:#fff;padding:2px 12px;border-radius:3px;font-weight:bold">#2b2b2b</span> |
88+
89+
## Implementation Notes
90+
91+
### Platform Variations
92+
93+
The standard colors above are the canonical reference. Individual
94+
tools may adapt them to fit their platform's conventions:
95+
96+
- **IntelliJ IDEA Plugin** — Maps token types to IntelliJ's
97+
`TextAttributesKey` system. Actual colors come from the user's
98+
selected theme (e.g., Darcula, IntelliJ Light) so they blend
99+
with the rest of the IDE.
100+
101+
- **VS Code Extension** — Uses TextMate scopes (e.g.,
102+
`keyword.control.riddl`, `support.type.riddl`). Colors are
103+
determined by the active VS Code color theme.
104+
105+
- **Synapify / ossum.ai Playground** — These Monaco-based editors
106+
use a Catppuccin-inspired palette and split the `Keyword` token
107+
into semantic sub-categories (definition keywords, statement
108+
keywords, modifier keywords, etc.) for finer-grained coloring.
109+
110+
- **This Documentation Site** — Uses a custom Pygments lexer
111+
(`riddl_lexer/`) with CSS overrides in `extra.css`. The colors
112+
in the tables above are taken directly from this implementation.
113+
114+
### Design Principles
115+
116+
The color scheme follows these principles:
117+
118+
1. **Semantic grouping** — Related tokens share color families
119+
(e.g., teal for types and punctuation, green for strings and
120+
documentation).
121+
122+
2. **Keywords stand out** — Burnt orange makes structural keywords
123+
immediately visible against a dark background.
124+
125+
3. **Comments recede** — Gray and italic styling keeps comments
126+
present but unobtrusive.
127+
128+
4. **Light/dark parity** — Each dark theme color has a
129+
corresponding light theme variant that maintains the same
130+
semantic associations at appropriate contrast levels.
131+
132+
### Adding RIDDL Highlighting to a New Tool
133+
134+
To implement RIDDL syntax highlighting in a new editor or tool:
135+
136+
1. **Tokenize** using the eleven `Token` types from the enum above
137+
2. **Map** each token type to your platform's highlighting system
138+
3. **Apply** the standard hex colors (or your platform's closest
139+
semantic equivalent)
140+
4. **Test** with both light and dark themes
141+
142+
The RIDDL compiler's `Lexer` produces these tokens directly—see
143+
`com.ossuminc.riddl.language.AST.Token` in the
144+
[riddl](https://github.com/ossuminc/riddl) repository.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,7 @@ nav:
266266
- References:
267267
- riddl/references/index.md
268268
- Cheat Sheet: riddl/references/cheat-sheet.md
269+
- Standard Highlighting: riddl/references/standard-highlighting.md
269270
- Language Reference: riddl/references/language-reference.md
270271
- EBNF Grammar: riddl/references/ebnf-grammar.md
271272
- Tools:

0 commit comments

Comments
 (0)