Module

themes._palette

Immutable palette definitions for Rosettes theming.

Provides frozen dataclasses for syntax highlighting palettes. All palettes are thread-safe by design.

Design Philosophy:

Palettes define colors for semantic roles, not individual tokens. This keeps themes manageable (~20 colors) while supporting 100+ token types.

Architecture:

  • SyntaxPalette: Single theme with fixed colors

    • ~20 color slots for semantic roles
    • Style modifiers (bold, italic)
    • CSS variable generation

  • AdaptivePalette: Light/dark mode support

    • Contains two SyntaxPalette instances
    • Generates@media (prefers-color-scheme)CSS

    Creating Palettes:

Minimal (only required fields):

>>> palette = SyntaxPalette(
...     name="minimal",
...     background="#1a1a1a",
...     text="#f0f0f0",
... )
>>> filled = palette.with_defaults()  # Fills missing colors

Complete (all roles specified):

>>> palette = SyntaxPalette(
...     name="complete",
...     background="#1a1a1a",
...     text="#f0f0f0",
...     string="#98c379",
...     number="#d19a66",
...     function="#61afef",
...     # ... all other roles ...
... )

CSS Generation:

>>> css_vars = palette.to_css_vars(indent=2)
>>> print(css_vars)
  --syntax-bg: #1a1a1a;
  --syntax-string: #98c379;
  ...

Thread-Safety:

Both classes are frozen dataclasses. Once created, they cannot be modified. Safe to share across threads.

See Also:

  • rosettes.themes: Palette registry and built-in palettes
  • rosettes.themes._roles: SyntaxRole enum (what the colors are for)
2Classes

Classes

SyntaxPalette 39 ▼
Immutable syntax highlighting palette. Thread-safe by design. Defines ~20 semantic color slots ins…

Immutable syntax highlighting palette.

Thread-safe by design. Defines ~20 semantic color slots instead of 100+ individual token colors.

Required Fields: name: Unique identifier for the palette background: Background color for code blocks text: Default text color

Optional Fields: All other fields default to empty string and are filled by with_defaults() using sensible fallbacks.

Attributes

Name Type Description
name str —
background str —
text str —
background_highlight str —
control_flow str —
declaration str —
import_ str —
string str —
number str —
boolean str —
type_ str —
function str —
variable str —
constant str —
comment str —
docstring str —
error str —
warning str —
added str —
removed str —
muted str —
punctuation str —
operator str —
attribute str —
namespace str —
tag str —
regex str —
escape str —
bold_control bool —
bold_declaration bool —
bold_type bool —
italic_comment bool —
italic_docstring bool —
italic_variable bool —

Methods

with_defaults 0 SyntaxPalette ▼
Return a new palette with empty fields filled from defaults.
def with_defaults(self) -> SyntaxPalette
Returns
SyntaxPalette
validate_contrast 2 dict[str, str] ▼
Return dict of role -> message for roles failing WCAG contrast.
def validate_contrast(self, *, level: Literal['AA', 'AAA'] = 'AA', large_text: bool = False) -> dict[str, str]
Parameters
Name Type Description
level —

"AA" (4.5:1 normal, 3:1 large) or "AAA" (7:1 normal, 4.5:1 large)

Default:'AA'
large_text —

If True, use large-text thresholds.

Default:False
Returns
dict[str, str] Empty dict if all roles pass. Otherwise role name -> failure message.
to_css_vars 1 str ▼
Generate CSS custom property declarations.
def to_css_vars(self, indent: int = 0) -> str
Parameters
Name Type Description
indent — Default:0
Returns
str
generate_css 1 str ▼
Generate complete CSS stylesheet for syntax highlighting. Generates CSS rules …
def generate_css(self, *, class_style: CssClassStyle = 'semantic') -> str

Generate complete CSS stylesheet for syntax highlighting.

Generates CSS rules for all semantic roles, suitable for use with the HTML formatter.

Parameters
Name Type Description
class_style —

CSS class naming style: - "semantic": Readable classes like .syntax-function - "pygments": Pygments-compatible classes like .nf

Default:'semantic'
Returns
str Complete CSS stylesheet as a string.
Internal Methods 1 ▼
__post_init__ 0 ▼
Validate palette after initialization.
def __post_init__(self) -> None
AdaptivePalette 6 ▼
Theme that adapts to light/dark mode preference. Wraps two SyntaxPalette instances for light and d…

Theme that adapts to light/dark mode preference.

Wraps two SyntaxPalette instances for light and dark mode. Generates CSS with @media (prefers-color-scheme) queries.

Thread-safe: frozen dataclass containing frozen palettes.

CSS Generation:

Adaptive palettes generate CSS with media queries:

@media (prefers-color-scheme: light) {
  :root { --syntax-bg: #ffffff; ... }
}
@media (prefers-color-scheme: dark) {
  :root { --syntax-bg: #0d1117; ... }
}

Attributes

Name Type Description
name str

Unique identifier for the adaptive palette
light SyntaxPalette

Palette for light mode (prefers-color-scheme: light)
dark SyntaxPalette

Palette for dark mode (prefers-color-scheme: dark)

Methods

validate_contrast 2 dict[str, str] ▼
Return contrast failures for both light and dark palettes. Combines results wi…
def validate_contrast(self, *, level: Literal['AA', 'AAA'] = 'AA', large_text: bool = False) -> dict[str, str]

Return contrast failures for both light and dark palettes.

Combines results with "light." and "dark." prefix for adaptive palettes.

Parameters
Name Type Description
level — Default:'AA'
large_text — Default:False
Returns
dict[str, str]
generate_css 1 str ▼
Generate adaptive CSS with light/dark mode support. Generates CSS with @media …
def generate_css(self, *, class_style: CssClassStyle = 'semantic') -> str

Generate adaptive CSS with light/dark mode support.

Generates CSS with @media (prefers-color-scheme) queries for automatic light/dark mode switching.

Parameters
Name Type Description
class_style —

CSS class naming style: - "semantic": Readable classes like .syntax-function - "pygments": Pygments-compatible classes like .nf

Default:'semantic'
Returns
str Complete CSS stylesheet with media queries.
Internal Methods 1 ▼
__post_init__ 0 ▼
Validate adaptive palette.
def __post_init__(self) -> None