ayu for Sublime Text: three colour schemes, a palette, and a set of file icons

What ayu solves, and who it is for

Sublime Text ships with a default interface, and swapping it means replacing two separate things: the UI theme that styles tabs, the sidebar and panels, and the colour scheme that styles the text itself. ayu packages both. The README describes it as a bright colour theme that comes in three versions, dark, mirage and light, for all-day comfortable work, handcrafted for Sublime Text.

The audience is narrow and specific. This is for people who already use Sublime Text and want a palette that also exists elsewhere, because the README lists ports to VS Code and links to ayutheme.com for more. If you are choosing an editor and a theme at the same time, ayu is not a reason to pick Sublime. It is a reason to make Sublime look consistent with the rest of your tooling.

How the theme is put together: themes, colour schemes and icons

The repository layout shows the split clearly. Each variant has two files at the top level: ayu-dark.sublime-theme and ayu-dark.sublime-color-scheme, and the same pair for light and mirage. The .sublime-theme file carries the UI, and the .sublime-color-scheme file carries the syntax colours. Activating a variant means setting both keys, which is why the README's settings example always shows the two lines together.

File icons work differently. The README states that ayu ships its own file icons, the same set as ayu for VS Code, but that Sublime Text needs the A File Icon package to show them. The division of labour is explicit: A File Icon decides which icon each file gets, and ayu supplies the artwork. File types without an ayu icon keep A File Icon's own. So the icons are not a self-contained feature of the theme; they are a contribution into another package's mapping.

The build tooling is separate from the runtime. package.json declares the package private, requires Node 22.18.0 or newer, and defines build, start and sync-icons scripts driven by tsx and src/build.ts. There is an Icons.py and an activation.py at the top level, plus a dependencies.json. None of this is needed to use the theme in Sublime; it is how the maintainer generates the distributed files.

Installing ayu from Package Control and activating it

The README gives Package Control as the recommended route. Open the command palette with cmd/ctrl + shift + p, type install package, then search for ayu and install it. The manual route is to download the latest release, extract it, rename the directory to ayu, and move it into your Sublime Packages directory, which you reach through Preferences > Browse packages.

After installing, the quickest activation is the command palette entry the README names:

# cmd/ctrl + shift + p, then type:
ayu: Activate theme

If you prefer to pin the variant yourself, the README shows the user settings block. Open Preferences > Settings and add the pair of keys for the variant you want:

"theme": "ayu-mirage.sublime-theme",
"color_scheme": "Packages/ayu/ayu-mirage.sublime-color-scheme",

Swap mirage for light or dark to change variant; the README lists all three pairs. Two optional settings are documented: ui_native_titlebar for a native titlebar on macOS, ui_separator to hide the separators between panels, which the README notes are shown by default, and ui_wide_scrollbars for wider scrollbars.

"ui_native_titlebar": true,
"ui_separator": false,
"ui_wide_scrollbars": true

If you want the file icons, install A File Icon as well; without it the README says the icons will not show.

Custom UI fonts and the limits of the settings surface

The README documents one deeper customisation: changing the UI font. Open the command palette, type Browse packages, go to /User, and create a file named after the variant you use, for example ayu-mirage.sublime-theme. In it you override classes such as sidebar_label, sidebar_heading, tab_label, label_control, quick_panel_label and quick_panel_path_label, each with a font.face key.

[
  { "class": "sidebar_label", "font.face": "Your Font" },
  { "class": "tab_label", "font.face": "Your Font" }
]

That is the whole documented customisation surface. There is no documented way to change individual syntax colours from the README; you would be editing the .sublime-color-scheme file directly, and the README does not describe doing that. If your workflow depends on per-scope colour tuning, treat the theme as a starting point you will fork rather than a configurable system.

Where ayu is the wrong choice

The clearest boundary is the editor. ayu here is a Sublime Text package. The README lists ports to VS Code and more at ayutheme.com, but those are separate projects with their own repositories, and nothing in this repository installs into another editor.

The second boundary is version. The README keeps a Legacy Versions section pointing Sublime Text 3 users at v5.1.0 and Sublime Text 2 users at v3.2.2, while the current release line is v6.2.0. The release notes show v6.1.2 was tagged for Sublime Text 3 compatibility, but the README's own guidance is to use the older tags on those builds. If you are pinned to Sublime Text 2, you are on a release that predates everything the current README documents.

The third is maintenance expectations around the icon set. Because icons come through A File Icon, a file type ayu has no artwork for falls back to A File Icon's icon. The README states this plainly, but it means coverage is a joint property of two packages and not something ayu controls alone.

ayu against a single-file colour scheme

The obvious alternative is a colour scheme that only replaces syntax colours and leaves the UI alone, which is how many Sublime themes are distributed. The difference in approach is scope. A colour scheme only file is a drop-in that cannot break your tabs, sidebar or panels, because it does not touch them. ayu sets a .sublime-theme alongside the .sublime-color-scheme, so it controls the whole window, and the README's settings example reflects that by always pairing the two keys.

That trade is worth naming. You get a consistent look across UI and code, and the ui_separator, ui_native_titlebar and ui_wide_scrollbars options exist precisely because a UI theme owns those decisions. In exchange, you are depending on the theme file staying compatible with your Sublime build, which is why the README keeps separate tags for older versions. If you only ever wanted different syntax colours, a scheme-only package is the smaller dependency.

Licence and the cost of keeping ayu current

The repository is MIT licensed, and package.json repeats the MIT identifier with Ike Ku as author. In practical terms that is a permissive licence: you can fork the theme files and ship your own variant. It is not legal advice, and if you redistribute a modified build you should read the LICENSE file in the repository rather than rely on the identifier alone.

Upgrade cost is low for users and non-trivial for anyone building from source. Users get new versions through Package Control or by replacing the directory in Packages. Building from source requires Node 22.18.0 or newer, then npm run build, which runs tsx ./src/build.ts; npm start runs the same script in watch mode. The sync-icons script fetches A File Icon's icons.json from GitHub into src/afi-icons.json, so regenerating icons depends on that upstream file remaining where the script expects it.

The last push to the repository was on 2026-09-27, and v6.2.0 was released the same day. The previous release, v6.1.2, dates from 2021-09-28, so the gap between v6.1.2 and v6.2.0 is five years. That is the real upgrade consideration: the project is not on a steady release cadence, so plan around the tagged releases rather than expecting frequent updates.

Editorial conclusion

Adopt ayu if you use Sublime Text and want the light, mirage and dark variants from one package, with an activation command and a documented settings block. Do not adopt it if you need a theme for an editor other than Sublime Text, or if you depend on the legacy Sublime Text 2 or 3 builds, which the README points to as older tagged releases rather than the current package. Before committing, verify two things: that Package Control resolves the ayu package in your Sublime build, and that the file icons appear after installing A File Icon, since the README states ayu supplies the artwork while A File Icon decides which icon each file gets.

Frequently asked questions

Official sources

1. dempfi/ayu on GitHub
2. License: MIT
3. Project website
4. README
5. Releases