Theme file format¶
Audience: anyone writing or checking a caret theme file.
A theme file is a JSON file that defines one caret theme: its name, its scheme (light or dark), the colors of the review page, and the colors that highlight code and, optionally, the plan's Markdown. caret derives every other color it needs, such as hairline rules, selection washes, and chip tints, from the colors the file names. To make one, see Make your own theme.
Where caret finds theme files¶
caret reads theme files from $XDG_CONFIG_HOME/caret/themes, or ~/.config/caret/themes
when XDG_CONFIG_HOME is unset. A missing or empty folder is fine.
Uploading a theme in Settings → Appearance
writes it into this folder.
caret rereads the folder each time the review page loads, so a file you add, edit, or delete takes effect on the next page load, without a restart. An uploaded theme appears straight away. Each theme appears in the theme picker for its scheme.
caret reads only the *.json files directly in the folder, including symlinks to files.
It ignores subfolders, other extensions, and names that start with ..
caret skips a file, and reports an error that names it, when the file:
- cannot be read, for example because of its permissions;
- is larger than 64 KiB;
- is not valid JSON, or fails the validation described below;
- uses the
idof a built-in theme; - shares its
idwith another file. caret skips every file with thatid.
Settings → Appearance lists each file that didn't load, with its errors, under the theme pickers. When the theme you selected for a scheme stops loading, caret shows its own theme for that scheme but keeps your selection, so restoring the file brings it back.
Top-level fields¶
| Field | Required | Value |
|---|---|---|
$schema |
No | A URL to the JSON Schema, for editor support. caret ignores it. |
id |
Yes | A lowercase slug of letters, digits, and single dashes, like my-theme. At most 64 characters. |
label |
Yes | The name shown in Settings. 1 to 64 characters, not all whitespace. |
scheme |
Yes | "light" or "dark". |
palette |
Yes | The interface colors, below. |
syntax |
Yes | The code highlighting roles, below. |
markdown |
No | The markdown element styles, below. |
palette¶
These 13 colors are required:
| Field | What it colors |
|---|---|
paper |
The page surface. In dark it is the darkest of the three surfaces; in light it sits between raised and sunk. |
raised |
The lightest surface in either scheme: cards, dialogs, the plan pane. |
sunk |
Code blocks and the diff body: lifted off paper in dark, recessed in light. |
ink |
Body text. |
inkSoft |
Secondary text. |
inkFaint |
Metadata. |
accent |
The current selection. |
accentBright |
The accent's hover step, a shade further from paper: hovers, links, inline code. |
accentInk |
Text drawn on top of accent. |
neutral |
A mid-tone neutral, used for the mark on an orphaned comment. |
ok |
Success and additions. |
danger |
Errors and deletions. |
attention |
The "look here" hue: the notification dot and the version-count badge. |
These 9 hue overrides are optional. Each one moves a derived color onto a different hue; caret still decides how strong it is.
| Field | What it colors | Default |
|---|---|---|
ruleHue |
The two hairline rules | ink |
washHue |
The selection wash | accent |
markHue |
The two highlight marks | washHue, then accent |
chipBoldHue |
The bold chip in the source view | ink |
chipItalicHue |
The italic chip in the source view | inkSoft |
chipCodeHue |
The inline-code chip in the source view | neutral |
chipLinkHue |
The link chip in the source view | accentBright |
chipRefHue |
The file-reference chip in the source view | ok |
chipSkillHue |
The skill chip in the source view | attention |
syntax¶
Each role is an object with a color and an optional fontStyle, a list of any of
"italic", "bold", "underline", and "strikethrough". A role without fontStyle
takes none from another role, but keeps the style of a comment or emphasized text it sits
in.
These 11 roles are required:
| Role | What it colors | Scopes |
|---|---|---|
comment |
Comments | comment, punctuation.definition.comment, string.comment |
punctuation |
Punctuation and separators | punctuation, punctuation.separator, punctuation.terminator, punctuation.accessor |
variable |
Variables and constants | variable.other.readwrite, variable, variable.other, variable.other.constant, meta.definition.variable, support.variable |
property |
Object properties and keys | variable.other.property, variable.other.object.property, meta.object-literal.key, support.type.property-name |
attribute |
Markup attributes | entity.other.attribute-name, meta.attribute |
keyword |
Keywords and storage modifiers | keyword, keyword.control, keyword.operator.new, keyword.operator.expression, storage, storage.type, storage.modifier |
function |
Function names and calls | entity.name.function, support.function, meta.function-call, variable.function |
type |
Types, classes, and namespaces | entity.name.type, entity.name.class, entity.other.inherited-class, entity.name.namespace, support.type, support.class |
string |
Strings | string, string.quoted, string.template, punctuation.definition.string, constant.other.symbol |
escape |
String escapes and regular expressions | constant.character.escape, string.regexp |
number |
Numbers and language constants such as true and null |
constant.numeric, constant.language, support.constant |
These 9 roles are optional. A file that omits one paints it with the role it falls back to, so add one only to set it apart.
| Role | What it colors | Scopes | Falls back to |
|---|---|---|---|
operator |
Operators | keyword.operator |
punctuation |
bracket |
Braces | meta.brace |
punctuation |
parameter |
Function parameters | variable.parameter |
variable |
languageVariable |
this, self, and similar |
variable.language |
keyword |
tag |
Markup tag names | entity.name.tag |
keyword |
tagPunctuation |
Markup tag brackets | punctuation.definition.tag |
keyword |
builtinFunction |
Built-in functions | support.function.builtin |
function |
builtinType |
Built-in and primitive types | support.type.primitive, support.type.builtin |
type |
interpolation |
Template interpolation delimiters | punctuation.definition.template-expression |
escape |
markdown¶
These optional styles color Markdown elements in the
source view, the preview, and the
comment editor. Each is an object with a color and an optional fontStyle, the same
shape as a syntax role. An element the file omits, or the whole markdown object, keeps
caret's default look.
| Element | What it colors | Source view default | Comment editor default |
|---|---|---|---|
heading |
A heading, its # markers included |
accent |
ink, bold |
heading1 to heading6 |
A markdown heading of that level | heading |
heading |
code |
Inline code, and the body of a fenced block | accentBright |
ink |
link |
A link's text | ink mixed toward accent |
accent |
bold |
Bold text, between its ** markers |
ink |
ink |
italic |
Italic text, between its _ or * markers |
ink |
ink |
listMarker |
A list's bullet and an ordered item's number | inkSoft and inkFaint |
inkFaint |
quote |
Blockquote text | ink, slightly faded |
inkSoft |
A markdown heading level without a style of its own takes heading's. A level's style
replaces heading whole, fontStyle included, so a level that names no fontStyle takes
none from it. A heading underlined with === is level 1, and one underlined with --- is
level 2. Headings in other formats, such as reStructuredText, AsciiDoc, Org, and MDX, in a
fenced block or a previewed file, carry no level caret reads, so heading styles every
one of them.
A few elements keep part of their look whatever the style says:
- Bold text stays bold, italic text stays italic, and a link keeps its dotted underline
and, in the source view, its chip. A
fontStyleadds to these. - A heading style sets the heading's weight on every surface, so name
"bold"for a bold heading. - A styled
quotepaints at full strength, since its color already sets it apart. - The
**,_, and backtick markers keep their own color. - A fenced block's body takes the
codecolor but not itsfontStyle.
The chip tint behind bold, italic, inline code, and link text comes from the chip*Hue
palette overrides, not from these styles.
In the preview, an unstyled element differs from the source view default in four ways: a
heading is semibold, a quote is inkSoft rather than faded, a link or emphasis draws no
chip, and a cited file takes the code style whether or not it was backticked. A link
whose label is prose, such as [the cache](src/cache.ts), keeps the sentence's style. The
preview leaves a fenced block's body to its own highlighting, so there code colors only
inline code and cited files.
In the comment editor, text nested in a heading, link, or quote takes that element's
color, and in a heading its weight too. A fenced block that names its language takes the
editor's own code colors rather than code.
Colors and errors¶
Every color is a six-digit hex color, #rrggbb, in either case. Shorthand (#fff), alpha
(#rrggbbaa), and color names are rejected.
caret rejects a file with any unknown field. For an invalid file, it reports one line per
failing field, as path: message, for example
palette.paper: must be a hex color like #1a2b3c.
Example¶
This is caret's own dark theme as a theme file:
{
"$schema": "https://raw.githubusercontent.com/macintacos/caret/HEAD/docs/theme.schema.json",
"id": "caret-dark",
"label": "caret dark",
"scheme": "dark",
"palette": {
"paper": "#0a0806",
"raised": "#15110d",
"sunk": "#100d0a",
"ink": "#f7f2ea",
"inkSoft": "#bcb0a1",
"inkFaint": "#918576",
"accent": "#ff8f3d",
"accentBright": "#ffb277",
"accentInk": "#0a0806",
"neutral": "#9a8c7e",
"ok": "#4ed056",
"danger": "#f65a6f",
"attention": "#3fbda9",
"ruleHue": "#f2e7d5",
"washHue": "#f2842f",
"markHue": "#ffa64d",
"chipLinkHue": "#f56f8e",
"chipSkillHue": "#6ec4e4"
},
"syntax": {
"comment": { "color": "#7f7466", "fontStyle": ["italic"] },
"punctuation": { "color": "#b0a094" },
"variable": { "color": "#ece2d4" },
"property": { "color": "#a3d4ec" },
"attribute": { "color": "#f5834f" },
"keyword": { "color": "#dd7a6c" },
"function": { "color": "#ecc25c" },
"type": { "color": "#6ec4e4" },
"string": { "color": "#92d474" },
"escape": { "color": "#f56f8e" },
"number": { "color": "#4cbbc8" }
},
"markdown": {
"heading": { "color": "#ecc25c", "fontStyle": ["bold"] },
"heading1": { "color": "#ecc25c", "fontStyle": ["bold", "italic"] },
"heading2": { "color": "#92d474", "fontStyle": ["bold"] },
"heading3": { "color": "#3fbda9", "fontStyle": ["bold"] },
"heading4": { "color": "#6ec4e4", "fontStyle": ["bold"] },
"heading5": { "color": "#ecc25c" },
"heading6": { "color": "#bcb0a1", "fontStyle": ["italic"] },
"code": { "color": "#a3d4ec" },
"link": { "color": "#f56f8e" },
"bold": { "color": "#dd7a6c" },
"italic": { "color": "#3fbda9" },
"listMarker": { "color": "#ecc25c" },
"quote": { "color": "#92d474", "fontStyle": ["italic"] }
}
}