atom/docs/creating-a-theme.md

Creating a Theme

Atom's interface is rendered using HTML and it's styled via LESS (a superset of CSS). Don't worry if you haven't heard of LESS before, it's just like CSS but with a few handy extensions.

Since CSS is the basis of the theming system, we can load multiple themes within Atom and they behaves just as they would on a website. Themes loaded first are overridden by themes which are loaded later (the order is controlled from within the Settings pane).

This flexibility is helpful for users which prefer a light interface with a dark syntax theme. Atom currently has only interface and syntax themes but it is possible to create a theme to style something specific — say a changing the colors in the tree view or creating a language specific syntax theme.

Getting Started

To create your own theme you'll need a few things:

• A working install of Atom, so you can work on your new theme.
• A working install of git to track changes.
• And a GitHub account, so you can distribute your themes.

Themes are pretty straight forward but it's still helpful to be familiar with a few things before starting:

• LESS is a superset of CSS but it has some really handy features like variables. If you aren't familiar with its syntax take a few minutes to familiarize yourself.
• Atom uses Chrome at its core, so you can use Chrome devtools to inspect the current state of the interface. Checkout Google's extensive tutorial for a short introduction.

Creating a Minimal Syntax Theme

1. Open the Command Palette (cmd-p)
2. Search for Package Generator: Generate Theme and select it.
3. Choose a name for the folder which will contain your theme.
4. An Atom window will open with your newly created theme.
5. Open package.json and update the relevant parts.
6. Open stylesheets/colors.less to change the various colors variables which have been already been defined.
7. Open stylesheets/base.less and modify the various syntax CSS selectors that have been already been defined.
8. When you're ready update the README.md and include an example screenshot of your new theme in action.
9. Open a terminal to your new theme directory
10. Run apm link to install it locally.
11. Reload Atom (cmd-r) and your theme should now be applied.
12. To publish, initialize a git repository, push to GitHub, and run apm publish.

Interface Themes

There are only two differences between interface and syntax themes - what they target and what they provide. Interface themes only target elements which are outside of the editor and must provide a ui-variables.less file which contains all of the variables provided by the core themes. Syntax themes don't need to provide any variables to other themes and only target elements within the editor.

Development workflow

There are a few of tools to help make theme development much faster.

Live Reload

Reloading via cmd-r after you make changes to your theme is slow. Atom supports live updating of styles on Dev Mode Atom windows.

1. Open your theme directory in a dev window by either using the File > Open in Dev Mode menu or the cmd-shift-o shortcut
2. Make a change to your theme file and save — your change should be immediately applied!

If you'd like to reload all styles at any time, you can use the shortcut cmd-ctrl-shift-r.

Developer Tools

Atom is based on the Chrome browser, and supports Chrome's Developer Tools. You can open them by selecting the View > Toggle Developer Tools or by using the cmd-option-i shortcut.

The dev tools allow you to inspect elements and take a look at their CSS properties.

Atom Styleguide

If you are creating an interface theme, you'll want a way to see how your theme changes affect all the components in the system. The styleguide is a page with every component Atom supports rendered.

To open the styleguide, open the command palette (cmd-p) and search for styleguide or use the shortcut cmd-ctrl-shift-g.