Tutorial

Make Sinclair yours: themes, fonts & appearance

This is the fun part. Everything that shapes how Sinclair looks — the theme, the colors, the typeface, the cursor, transparency, padding — is a plain line in your config file, and every one of them applies live the moment you save. No restart, no reload dance. Keep the file open in one pane, edit in another, and watch the window repaint as you type your way to a terminal that feels like yours.

1. Pick a theme

Start with a base. The theme key takes any of Sinclair's 22 hand-tuned built-ins — a big enough library that you'll almost certainly find one you like before you touch a single color:

{ "theme": "tokyo night" }

Names are forgiving: they're case-insensitive and ignore spaces, dashes, and underscores, so tokyo night, tokyo-night, and TokyoNight all land on the same scheme. Prefer to point and click? The GUI settings (⌘,) include a theme picker that writes this exact key for you — same result, same live repaint. Here's the full set and the value to pass:

2. Follow the OS light/dark automatically

If your desktop flips between light and dark through the day, Sinclair can follow it. Set theme-light and theme-dark to a scheme each, and Sinclair watches the OS appearance and rebuilds its colors live when it flips — picking the matching one, no restart and no manual toggle:

// ~/.config/sinclair/settings.json
{
  "theme-light": "github light",
  "theme-dark": "github dark"
}

Either key works on its own: whichever is set wins for that appearance, and plain theme is the fallback for the other. Set all three and you get a bright scheme by day, a dark one by night, and a safety net if neither matches.

3. Override individual colors

You don't have to take a theme as-is. These keys layer your own colors on top of the selected scheme, so you can start from a base you like and tweak only the parts that bug you:

The palette key is the powerful one: it recolors a single ANSI slot, with N from 0–255 — 0–7 the standard colors, 8–15 the bright variants, 16–231 the 6×6×6 color cube, and 232–255 the grayscale ramp. Repeat it to remap as many slots as you want:

{
  // start from a base theme, then override
  "theme": "tokyo night",
  "background": "#0b0e14",
  "cursor-color": "#ffcc66",

  // recolor ANSI red (index 1) and bright black (index 8)
  "palette": ["1=#ff5555", "8=#5c6370"]
}

4. Fonts & ligatures

The font keys control the typeface, its size, and its OpenType behavior. The trick worth knowing: font-family is repeatable, and each entry builds a fallback chain — the first is your primary face, later ones cover glyphs it's missing (emoji, box-drawing, an odd symbol). List your favorite first, a dependable face second:

{
  "font-family": ["JetBrains Mono", "Menlo"],
  "font-size": 14,
  "font-style": "normal",
  "font-feature": ["+liga", "cv01=2"],
  "adjust-cell-height": 2
}

font-feature is where a font's personality lives. Turn ligatures on with +liga (or off with -calt), switch on a stylistic set like ss01, or pick a character variant with cv01=2 — one feature per line, repeat as needed. If the cell metrics feel a touch tight or loose for your face, adjust-cell-width and adjust-cell-height nudge them by a pixel or two (either can go negative).

5. Cursor

Small detail, big difference in how the terminal feels to type in. Four keys shape the cursor's shape, blink, and color:

{
  "cursor-style": "bar",
  "cursor-style-blink": true,
  "cursor-color": "#ffcc66",
  "cursor-text": "#0b0e14"
}

Go block for the classic terminal look, bar for an editor feel, or underline for something quieter. If you pick a bold cursor-color with a block cursor, set cursor-text to keep the character it sits on readable against the fill.

6. Transparency, background image & readability

A few keys shape the terminal surface itself. This is where a setup goes from "nice theme" to "that's my terminal":

• background-opacity (0.2–1.0) makes the window translucent — the terminal background lets the desktop through while colored cells stay opaque.
• background-image draws an image behind the terminal; combine it with a lowered background-opacity so the image shows through.
• minimum-contrast (1–21) nudges each cell's foreground toward black or white until it meets that WCAG contrast ratio against its background — a floor on readability for low-contrast color schemes.
• badge paints a faint watermark in each pane's corner, with {cwd} and {host} substituted per pane.

// ~/.config/sinclair/settings.json
{
  "background-opacity": 0.85,
  "background-image": "~/Pictures/wallpaper.png",
  "minimum-contrast": 4.5,
  "badge": "{host} · {cwd}"
}

7. Padding & polish

Last, the finishing touches — the spacing and rendering options that make the whole thing feel deliberate:

{
  "window-padding-x": 8,
  "window-padding-y": 6,
  "unfocused-split-opacity": 0.6,
  "bold-is-bright": true
}

A little breathing room goes a long way — bump window-padding-x and window-padding-y up from their default of 2 so text isn't jammed against the window edge. Lower unfocused-split-opacity to make the active pane pop harder when you're working in a grid of splits. And bold-is-bright gives bold text extra punch by rendering it in the bright color variant — a classic terminal look that reads well against most themes.

Where to next