Lexicon

A Semantic Syntax Theme System

A color vocabulary for code.

Currently for C# in Visual Studio with Codist. More to come.

You already know the difference between a class and a struct. Between an if statement and a method call. Between a constant and a variable. Lexicon makes your editor know it too. Every color carries meaning. Purple is always a reference type. Blue is always a value type. Orange is always a decision point. Once you learn the vocabulary, any C# codebase using Lexicon becomes easier to read—not because the code changed, but because you can see its structure at a glance.

Theme Preview

This code sample demonstrates the Lexicon semantic syntax system. Use the theme selector to compare how each palette renders the same code.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Lexicon.Demo;

// Interface: cyan + italic (behavioral contract)
public interface IDocumentProcessor
{
    // Property: light blue (encapsulated access)
    int ProcessedCount { get; }
    
    // Callable: yellow (executable behavior)
    Task<ProcessingResult> ProcessAsync(IEnumerable<Document> documents);
}

See the full sample in Complete Example and the palette in Lexicon Twilight below.

1. Problems and Goals

Lexicon addresses specific pain points that developers encounter when reading and reviewing code. Traditional syntax highlighting colors code by grammatical category: keywords in one color, strings in another, comments in gray. While this provides basic visual structure, it fails to surface semantic distinctions that matter for comprehension and debugging.

Problems with Traditional Syntax Highlighting

Semantic blindness. A traditional theme might color DateTime and Exception identically because both are type names. But DateTime is a value type (stack-allocated, copy semantics) while Exception is a reference type (heap-allocated, polymorphic). This distinction affects memory management, equality behavior, and API design—information worth surfacing visually, especially when debugging mutation or aliasing bugs.

Control flow invisibility. When tracing execution paths, developers need to identify decision points (if, switch) and iteration (for, while). Traditional themes color these the same as class and public—all "keywords." This forces cognitive search for the specific keywords that affect execution flow.

Exception boundary opacity. Exception handling constructs (try, catch, throw) define critical error boundaries. Traditional highlighting provides no visual distinction between these and other keywords, making it harder to quickly assess error handling coverage during code review.

Closure hazards hidden. Variables captured by lambdas or local functions have different lifetime and mutation semantics than ordinary locals. This is a common source of bugs (the classic loop-variable-capture issue), yet traditional highlighting provides no visual indication that a variable is captured.

Design Goals

2. Scope and Audience

Current Implementation

Lexicon is currently implemented for C# development in Visual Studio 2026 using the Codist extension. The system depends on Codist's extended semantic classification capabilities, which go beyond Visual Studio's built-in Roslyn classifications. Without Codist, Lexicon's full semantic vocabulary cannot be rendered.

The scope is deliberately focused: one language, one IDE, one extension. The design aspiration is that the semantic vocabulary could eventually extend to other languages and editors, but this would require adaptation work. For now, Lexicon is where C# lives.

Target Users

Lexicon is designed for developers who already understand C# syntax and semantics. It surfaces semantic distinctions rather than teaching language fundamentals. Three primary user populations and their tasks inform the design:

3. Design Philosophy

Traditional syntax highlighting answers the question "What grammatical category is this token?" Lexicon answers a different question: "What role does this code element play in program execution?"

When you see a block of code styled with Lexicon, you don't parse tokens—you see patterns of meaning. Purple clusters indicate reference types. Cyan italic marks abstraction boundaries. Orange bold signals execution flow decisions.

Semantic vs. Grammatical Highlighting

The key difference is not just what is distinguished, but why. Lexicon's categories are chosen to support specific developer tasks—debugging, code review, onboarding—not to mirror compiler internals.

4. Theme Collection

All Lexicon themes share the same semantic mappings and decorations. What varies is the palette—the specific colors assigned to each category—and the emotional feel. Themes are different aesthetic schemes over the same vocabulary. Choose based on your environment, your vision, or simply what feels right.

5. Research Foundations

This section reviews research that informed Lexicon's design. These studies provide theoretical grounding and design principles for the semantic approach. See Section 12 for validation status.

Program Comprehension and Visual Cues

In 1988, Ronald Baecker demonstrated that visual enhancements could improve program comprehension. His study found that improved layout—combining typography, indentation, and color—increased correct answers by 11% and improved readability by 25%.^[1] These improvements came from combined visual enhancements, providing evidence that thoughtful visual design aids code reading.

A 2015 eye-tracking study by Advait Sarkar found that developers reading highlighted code exhibited lower cognitive load indicators than those reading plain text.^[2] The benefit became weaker with increased programming experience, suggesting that highlighting may provide greatest benefit during onboarding to unfamiliar codebases—one of Lexicon's explicit design goals.

The most important finding for semantic highlighting comes from Gilmore and Green's work on "programming plans."^[3] Their study found that visual cues only helped when they matched the task at hand. Participants found surface bugs faster with control-structure highlighting, but deep bugs faster with cognitive-plan coloring. This insight drives Lexicon's category selection: categories are chosen to align with tasks developers actually perform.

Color Psychology

Elliot and Maier's Color-in-Context Theory^[4] establishes that color carries psychological meaning and influences cognitive processing, often without conscious awareness. Lexicon uses this as a design heuristic: warm colors (orange) for attention-demanding constructs like control flow, cool colors (blue, purple) for structural elements, desaturated red (coral) for exceptions to distinguish from IDE error markers.

Color has meaning, and this has a direct and automatic influence on cognitive processes, including attention.
— Elliot & Maier, Color-in-Context Theory

Category Count

George Miller's (1956) "seven plus or minus two" finding^[5] concerns serial recall of arbitrary items in short-term memory—not visual categorization. Research on visual search suggests that practiced users can distinguish many more than seven categories when the categories are meaningful and consistent. Lexicon's eleven semantic categories cluster into related groups (types, data, flow) that map to distinctions developers already make. With use, the vocabulary becomes intuitive.

6. The Semantic Map

The semantic map defines eleven categories of code elements, each assigned a consistent color role across all theme variations. This mapping reflects how developers conceptualize code architecture during debugging and review tasks.

* The when keyword is only styled as an exception keyword when it appears in a catch clause filter (e.g., catch (Exception ex) when (...)). In pattern matching contexts such as switch expressions, when is styled as a regular keyword since it serves control flow rather than exception handling.

6.1 Category Rationale

Following Gilmore and Green's finding that visual cues help only when matched to task, each category was selected based on specific developer tasks where the distinction provides value.

Reference Types vs. Value Types

The distinction between reference types (purple) and value types (blue) is fundamental to C# programming and directly affects debugging. When a List<Order> is passed to a method, modifications affect the original—the caller and callee share the same object. When a DateTime is passed, the method receives a copy. Mutation bugs, aliasing issues, and null reference exceptions all trace back to this distinction. Making it visible accelerates root cause analysis.

Task alignment: Debugging mutation/aliasing bugs, understanding equality semantics, API design review.

Interfaces

Interfaces (cyan italic) mark abstraction boundaries—behavioral contracts that define how components interact. The italic styling reinforces that interfaces represent indirection: what you see in the code (the interface type) might not be what runs (the concrete implementation). During code review, cyan italic clusters indicate areas where behavior varies at runtime.

Task alignment: Architecture review, dependency analysis, understanding testability and mock boundaries.

Callables

Callables (yellow) represent executable behavior—methods, constructors, local functions. Yellow is used because callables are action points: locations where execution transfers, where side effects occur, where work happens. In a sea of data and types, yellow marks the verbs.

Task alignment: Understanding execution flow, identifying side effects, performance analysis.

Data

Data (light blue) encompasses all named storage: fields, properties, parameters, and locals. These are unified because from a reading perspective, they all represent "a place where a value lives." The naming convention (_field vs local) already distinguishes scope; color distinguishes the semantic category "storage" from "type" and "action."

Const fields and readonly fields share the Data color but use bold styling to signal immutability. This keeps them visually connected to other data (they're still storage locations) while clearly marking that their values cannot change. During debugging, bold data members are safe harbors—they're not the source of unexpected state changes.

Task alignment: Understanding data flow, tracking state changes, identifying unused variables, magic number auditing.

Control Flow

Control flow (orange, bold) unifies all execution-path keywords: conditionals (if, switch), loops (for, while, foreach), and jumps (break, continue, return). Traditional highlighting scatters these among generic "keywords." Lexicon makes decision points visible at a glance.

Task alignment: Tracing execution paths, understanding branching complexity, debugging state-dependent behavior.

Exceptions

Exception handling (coral) marks error boundaries: try, catch, throw, finally, and the when filter in catch clauses. Note that when in pattern matching contexts (switch expressions) remains a regular keyword, as it serves control flow rather than exception handling. Coral is used rather than bright red to distinguish from IDE error squiggles—exception handling is intentional error management, not an error. During code review, coral blocks show where errors are expected and handled.

Task alignment: Reviewing error handling coverage, understanding failure modes, ensuring cleanup code runs.

String Literals vs. Literal Values

String literals (green) and literal values (amber) are separated because they require different developer attention. Strings often need localization review, format verification, or resource management consideration. Literal values—numbers, boolean literals, null, and enum members—often need magic-constant auditing or constant extraction. Keeping them visually distinct supports targeted review tasks.

The Literal Values category includes true, false, null, and enum members because these share the semantic character of numeric literals: they are raw, literal values written directly in code rather than computed or referenced from storage. Enum members like ProcessingStatus.Success are conceptually the same as writing a numeric constant—they're named literal values. The bold styling on enum members signals their fixed nature while the amber color groups them with other literals.

Task alignment: Localization review (strings), magic-constant audit (literal values), identifying hardcoded values.

Namespaces and Keywords

Namespaces (teal) provide organizational context. Keywords (soft purple) cover language reserved words that don't fit other categories—structural keywords like class, public, and async. These form the grammatical backbone of the code without demanding special attention.

For a compact reminder of these eleven categories, see Quick Reference below.

7. Decorations and Visual Hierarchy

Visual hierarchy research is clear: every element competes for attention. When everything is bold, nothing is bold. Codist offers dozens of styling options, but Lexicon uses only six, each passing a simple test: does this tell me something color alone cannot?

7.1 Decoration Precedence

When multiple decorations could apply to a single token, Lexicon follows a defined precedence hierarchy:

Combination rules: Background tint combines with bold and italic (a captured constant shows both bold and background tint). Strikethrough overrides dimming. When a token is both obsolete and captured, strikethrough takes precedence but the background tint is preserved if technically possible.

Interpretation Notes

Bold = Immutability, not emphasis. In typical text, bold means "important." In Lexicon, bold means "fixed at compile time." This is a learned convention.

Italic = Indirection, not emphasis. Italic marks elements where the actual behavior may differ from what the source code shows (interfaces, virtual methods, extension methods).

Coral ≠ Error. Exception handling uses coral (desaturated red) deliberately to distinguish from IDE error markers (bright red). This avoids alarm fatigue in codebases with extensive exception handling.

8. Implementation

Lexicon is implemented for Visual Studio 2026 with the Codist extension. This section explains requirements and capabilities.

Why Codist Is Required

Visual Studio provides semantic tokens through its Roslyn-based classification system, but Lexicon requires capabilities that Codist adds:

• Captured variable detection: Codist identifies variables captured by lambdas, enabling the closure warning background tint.
• Control flow keyword distinction: Codist separates if, for, while from other keywords.
• Font variations: Codist allows per-element font weight, style, and size, enabling bold constants, italic interfaces, and smaller attributes.
• Comment structure: Codist recognizes comment headings and task markers.

Classification Gaps

Even with Codist, some desired classifications are not available:

Installation

1. Install the Codist extension from the Visual Studio Marketplace.

2. Open Codist settings (Tools → Codist → Options).

3. Import the desired Lexicon theme file (JSON).

Getting Started with Lexicon

To experience Lexicon effectively on first use, follow this simple path:

• Start with the Lexicon Twilight theme, which is the reference palette described throughout this document.
• Open a familiar C# file and compare how types, data, and control-flow constructs stand out relative to your previous theme.
• If you need additional contrast or specific accessibility accommodations, evaluate other themes in the collection, especially Beacon.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Lexicon.Demo;

// Interface: cyan + italic (behavioral contract)
public interface IDocumentProcessor
{
    // Property: light blue (encapsulated access)
    int ProcessedCount { get; }
    
    // Callable: yellow (executable behavior)
    Task<ProcessingResult> ProcessAsync(IEnumerable<Document> documents);
}

// Reference type: purple (heap-allocated, polymorphic)
[ServiceLifetime(ServiceLifetime.Scoped)]
public class DocumentProcessor : IDocumentProcessor, IDisposable
{
    // # Constants (data + bold)
    private const int MaxRetries = 3;
    private const string DefaultName = "Untitled";
    
    // # Fields
    private readonly ILogger _logger;
    private bool _isDisposed;
    
    // Property: light blue
    public int ProcessedCount { get; private set; }
    
    public DocumentProcessor(ILogger logger)
    {
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }
    
    public async Task<ProcessingResult> ProcessAsync(IEnumerable<Document> documents)
    {
        var results = new List<DocumentResult>();
        var retryCount = 0;
        
        // Control flow: orange + bold (execution path decisions)
        foreach (var document in documents)
        {
            try
            {
                // Captured variable: background tint (closure warning)
                var result = await RetryAsync(async () =>
                {
                    retryCount++;  // CAPTURED by lambda
                    return await ProcessSingleAsync(document);
                }, MaxRetries);
                
                results.Add(result);
                ProcessedCount++;
            }
            catch (ProcessingException ex) when (ex.IsRetryable)
            {
                _logger.LogWarning($"Retryable: {ex.Message}");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Processing failed");
                throw;
            }
        }
        
        // Switch expression with pattern matching
        var status = results.Count switch
        {
            0 => ProcessingStatus.NoDocuments,
            _ when results.All(r => r.Success) => ProcessingStatus.AllSucceeded,
            _ => ProcessingStatus.PartialSuccess
        };
        
        return new ProcessingResult(results, status);
    }
    
    // Obsolete method: strikethrough decoration
    [Obsolete("Use ProcessAsync instead")]
    public void Process(Document doc) => throw new NotSupportedException();
}

// Value type (struct): blue
public readonly struct ProcessingResult
{
    public IReadOnlyList<DocumentResult> Results { get; }
    public ProcessingStatus Status { get; }
}

// Enum: blue (value type), members are literal values (amber + bold)
public enum ProcessingStatus
{
    NoDocuments,
    AllSucceeded,
    PartialSuccess,
    AllFailed
}

11. Accessibility Considerations

Lexicon addresses accessibility through a dedicated high-contrast theme (Beacon), careful contrast consideration in the flagship theme (Twilight), and documented limitations. This section presents calculated accessibility data and acknowledges testing gaps.

11.1 WCAG Contrast Ratios

The Web Content Accessibility Guidelines (WCAG) 2.1 specify minimum contrast ratios: Level AA requires 4.5:1 for normal text; Level AAA requires 7:1.^[6] The following table presents calculated contrast ratios for Lexicon Twilight against background #0d1117. These are computed values using the WCAG relative luminance formula; actual display contrast varies with monitor calibration, ambient lighting, and individual vision.

All Twilight colors meet WCAG 2.1 Level AA requirements (4.5:1 minimum). Nine of eleven categories meet Level AAA (7:1). The two categories meeting only AA (Value Types at 6.8:1 and Keywords at 6.0:1) remain well above the minimum threshold.

11.2 Color Vision Deficiency

Approximately 8% of males and 0.5% of females have some form of color vision deficiency (CVD). Lexicon's palette presents potential challenges:

Deuteranopia/Protanopia (red-green, most common): Orange (control flow) and green (string literals) may be difficult to distinguish. The design partially mitigates this by using bold weight on control flow, providing a non-color differentiation cue. However, simulation testing has not been performed.

Tritanopia (blue-yellow): Purple (reference types) and blue (value types) may be difficult to distinguish. This affects a core semantic distinction. Users with tritanopia should consider the Beacon theme, which maximizes lightness separation between all hues.

11.3 Italic Readability

Some developers, including those with dyslexia or certain visual processing differences, may find italic text harder to read. Interfaces and virtual methods use italic styling; this is a trade-off between semantic meaning and readability.

Users who find italics hard to read can adjust Lexicon themes by using a variant with italics removed or by overriding font style for interfaces and virtual methods in Codist's classification settings.

11.4 High Saturation

The Neon and Beacon themes use high-saturation colors that may cause visual fatigue for some users. The Whisper, Glacier, and Patina themes offer lower-saturation alternatives.

12. Limitations and Validation Status

Lexicon's design is informed by research on program comprehension, syntax highlighting, and color psychology—but Lexicon itself has not been empirically validated. This section consolidates the key limitations and validation gaps.

Research Status

Research-informed, not empirically validated. The studies cited in this document provide theoretical grounding and design principles; they do not validate that Lexicon's specific implementation produces the intended benefits.

Design hypotheses, not measured outcomes. Any benefits for comprehension speed, error detection rate, or cognitive load reduction are design hypotheses based on the research literature. Formal user studies would be needed to measure whether Lexicon actually delivers these benefits in practice.

Calculated accessibility values. The WCAG contrast ratios presented in Section 11 are calculated using standard formulas, not measured on actual hardware under controlled display conditions. Real-world contrast depends on monitor calibration, ambient lighting, and display technology.

No formal user studies. No controlled experiments have been conducted on Lexicon specifically. The design is informed by prior research on syntax highlighting and program comprehension, but has not been independently validated.

Known Limitations

Single language: Lexicon currently supports only C#. The semantic vocabulary is designed with C#'s type system in mind.

Extension dependency: Codist is required for full functionality. Some semantic distinctions (captured variables, control flow separation) cannot be rendered without it.

Color reliance: Lexicon relies heavily on color to convey meaning. Developers with certain forms of color vision deficiency may find some distinctions difficult to perceive, even with the Beacon theme.

13. Future Directions

User Studies

Controlled comparison of task performance between Lexicon and traditional highlighting would help validate (or refute) the design hypotheses. Useful metrics would include comprehension speed, bug detection rate, and subjective cognitive load ratings.

Accessibility Validation

Laboratory measurement of contrast ratios on calibrated displays, CVD simulation testing, and usability testing with accessibility-needs populations would strengthen the accessibility claims.

Editor and Language Expansion

Expanding to other editors (particularly VS Code) and other languages with similar type systems would allow the semantic vocabulary to benefit a wider range of developers.