Terminal Colors Architecture (TCA) Specification

March 28, 2026 · View on GitHub

Version: 0.4.0
Status: Draft

Overview

Terminal Colors Architecture (TCA) is a specification for defining terminal application color themes in a structured, portable format for use by developers and theme authors. TCA uses Tinted Theming base24 as the base format specification and adds a UI/TUI semantic layer definition, theme file location, user preference configuration and library validation specifications.

Goals

Portability - Single theme file works across terminals, editors, and frameworks
Interoperability - Structured ANSI, Base16/24, semantic, and UI naming scheme allows for easy library integration
Consistency - Structured approach to semantic color naming
Accessibility - Built-in contrast validation and WCAG compliance

File Format

TCA themes are base24 YAML files following the Tinted Theming base24 schema.

File naming convention: kebab-case.yaml (e.g., nord-dark.yaml, solarized-light.yaml)

File Location

In order to facilitate theme sharing between applications, per-user theme and preference files must be located in common directories. TCA respects the XDG Directory Specification.

TCA themes must be installed into $XDG_DATA_HOME/tca/themes/ (default: ~/.local/share/tca/themes/).

User Preferences File

User preferences must be stored in a TOML file at $XDG_CONFIG_HOME/tca/tca.toml with the following structure:

[tca]
default_theme = "User Default Theme"
default_dark_theme = "user-default-dark-theme"
default_light_theme = "userDefaultLightTheme"

Theme names can be in any standard case that can be folded into kebab-case.

All entries are optional. Fallback precedence should be:

Individual application preferences.
default_dark_theme if defined and terminal is in dark mode.
default_light_theme if defined and terminal is in light mode.
default_theme if the other preferences are not defined or terminal mode is unavailable.
Any defined theme if the others are not defined.

If no themes are defined or the user preference file is missing, any theme may be used.

Platform Notes

Non-XDG compliant platforms (e.g. Windows) should follow platform conventions. Use of a standard cross-platform directory library is recommended.

Semantic Mapping

TCA maps base24 fields to a structured set of names for library and application code. The tables below use dot notation (section.field) to identify fields. Library code should use idiomatic naming for the target language — for example, meta.name in spec notation maps to theme.meta.name in code, and ui.fg.primary maps to theme.ui.fg_primary.

Section	Description
meta	Information about the theme
ansi	16 ANSI terminal colors
semantic	Semantic colors
ui	UI element colors

Metadata Fields

Field	Base24 Map	Description
`name`	`name`	Human-readable theme name
`author`	`author`	Theme author name or organization
`dark`	`variant`	`true` if variant is `dark`, else `false`

ANSI Fields

Field	Base24 Map
black	base00
red	base08
green	base0b
yellow	base0a
blue	base0d
magenta	base0e
cyan	base0c
white	base05
bright_black	base03
bright_red	base12
bright_green	base14
bright_yellow	base13
bright_blue	base16
bright_magenta	base17
bright_cyan	base15
bright_white	base07

Semantic Section

Field	Base24 Map	Example Use
`error`	base08	Red text for errors
`warning`	base09	Yellow/orange warnings
`info`	base0c	Cyan info text
`success`	base0b	Green checkmarks
`highlight`	base0e	Selection, search results
`link`	base0d	Clickable links

UI Section

Field	Base24 Map	Example Use
`fg.primary`	base05	Primary text color
`fg.secondary`	base06	Secondary text color
`fg.muted`	base04	Muted/dimmed text
`bg.primary`	base00	Primary background color
`bg.secondary`	base01	Secondary/alternate background
`border.primary`	base02	Primary border color
`border.muted`	base01	Subtle/muted borders
`cursor.primary`	base05	Active cursor color
`cursor.muted`	base04	Inactive cursor color
`selection.bg`	base02	Selection background
`selection.fg`	base05	Selection foreground/text

Library Conformance

A TCA library must satisfy the following requirements.

Loading

A library MUST be able to load a base24 YAML theme file from a path.
A library MUST be able to load themes from the XDG theme directory.
A library MUST respect the user preference fallback chain defined in this spec.
A library SHOULD support loading themes by name in any common case format (snake_case, CamelCase, etc.) and fold them to kebab-case for lookup.
A library MAY provide built-in themes.

Mapping

A library MUST expose all fields defined in the semantic mapping tables under their canonical names.
A library MUST expose colors in the native color type of its target framework or language.
A library MUST expose meta.dark as a bool derived from the base24 variant field (true if variant is dark, false otherwise). When dark/light mode context is needed and the environment does not provide it, meta.dark should be used.

API

A library MUST provide access to mapped fields using idiomatic naming for its language (e.g. theme.semantic.error, theme.ui.bg_primary).
A library MUST provide a default theme that can be used without any theme files present.
A library SHOULD provide a builder or equivalent for constructing themes programmatically.
A library SHOULD expose base24 slot values directly for interoperability with non-TCA tooling.

Validation

A library SHOULD warn when a loaded theme fails contrast recommendations.
A library MAY provide a standalone validation tool.

Validation Rules

TCA themes must pass the following validation checks:

1. Structure Validation

Valid base24 syntax

2. Contrast Validation (Recommended)

For accessibility the following minimum contrast ratios are recommended:

Fields	Recommended	Warning	Error
fg.primary / bg.*	> 4.5	< 3.5	< 3.0
fg.muted / bg.*	> 3.0	< 2.5	< 2.0
semantic.* / bg.*	> 4.5	< 3.5	< 3.0
selection.fg / selection.bg	> 3.0	< 2.5	< 2.0
border.* / bg.*	> 3.0	< 2.5	< 2.0
cursor.primary / bg.*	> 4.5	< 3.5	< 3.0
cursor.muted / bg.*	> 3.0	< 2.5	< 2.0