Themes

Athas includes light and dark themes and supports persistent custom themes through JSON files.

Change the active theme

1. Open Settings with Cmd+, on macOS or Ctrl+, on Windows and Linux.
2. Go to Appearance.
3. Choose a theme under Color Theme.

You can also open the Command Palette, search for Change Theme, and select a theme. Moving through the results previews each theme before you confirm it.

Create a custom theme

The built-in generator gives you a complete starting file based on any installed theme:

1. Open Settings → Appearance → Custom Themes.
2. Select Create.
3. Enter a display name and a unique ID.
4. Choose the installed theme you want to use as a base.
5. Edit the generated JSON.
6. Select Install Theme to use it immediately, or Save JSON to keep the file without installing it.

The editor validates the JSON before saving or installing it and shows the exact property path for each problem.

Import a theme

Select Import under Settings → Appearance → Custom Themes and choose a .json file. You can also import from the theme picker in the Command Palette.

Imported themes are stored by Athas and remain available after restarting the app. A file can contain multiple variants, such as one light theme and one dark theme. Importing the same custom theme ID again updates that theme. Built-in and extension theme IDs cannot be overwritten.

Use the remove button beside an imported theme in Appearance settings to uninstall it. If the removed theme is active, Athas switches back to the matching default theme.

Theme file format

A theme file contains family metadata and a non-empty themes array:

{
  "name": "Forest",
  "author": "Your name",
  "description": "Muted forest colors",
  "version": "1.0.0",
  "themes": [
    {
      "id": "forest-night",
      "name": "Forest Night",
      "description": "A dark forest theme",
      "appearance": "dark",
      "colors": {
        "primary-bg": "#161a17",
        "secondary-bg": "#101311",
        "text": "#e7ebe8",
        "text-light": "#bdc7c0",
        "text-lighter": "#7f8d84",
        "border": "#2b332e",
        "hover": "#202722",
        "selected": "#29322b",
        "accent": "#8fb996",
        "error": "#df8175",
        "warning": "#d7ad70",
        "success": "#8fb996",
        "info": "#82aeb8",
        "selection-bg": "rgba(143, 185, 150, 0.25)"
      },
      "syntax": {
        "comment": "#738078",
        "keyword": "#df8175",
        "string": "#82aeb8",
        "number": "#d7ad70",
        "function": "#a4c99f",
        "variable": "#c4a7cb",
        "constant": "#df8175",
        "property": "#8ab7dc",
        "type": "#b8c98f",
        "operator": "#a3aaa5",
        "punctuation": "#a3aaa5"
      }
    }
  ]
}

Each theme requires:

• id: starts with a lowercase letter or number and contains only lowercase letters, numbers, dots, underscores, or hyphens
• name: the label shown in Athas
• appearance: either dark or light
• colors: the UI color map

The required UI colors are primary-bg, secondary-bg, text, text-light, text-lighter, border, hover, selected, and accent.

The syntax map is optional. Athas supplies readable syntax defaults for missing entries. Common entries include comment, keyword, string, number, function, variable, constant, property, type, operator, punctuation, boolean, null, regex, tag, and attribute.

Additional UI colors can control cursors, selections, Git status colors, and terminal ANSI colors. The generator includes every color supported by its selected base theme, making it the easiest way to discover and customize the full set.

Troubleshooting imports

Athas reports invalid JSON separately from schema errors. Schema messages include paths such as themes[0].colors.primary-bg, so you can locate the failing value directly.

If a file from VS Code or another editor fails to import, convert it to the Athas structure above first. Other editors use different token names and theme schemas, so their files are not directly compatible.