# Themes

Source: https://athas.dev/docs/themes

Create, import, and manage custom Athas color 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 integration 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:

```json
{
  "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.

## Share or maintain a theme

Keep the source JSON in version control and re-import the same ID to update it. Personal theme imports
do not publish to the [Integrations catalog](https://athas.dev/docs/integrations). [Settings](https://athas.dev/docs/settings) keeps
editor and UI fonts separate from color themes.