Anatomy of a GTK theme.
A theme looks like a single choice in a settings menu. Under the surface it is a folder of instructions, images, and metadata that a toolkit reads in a fixed order. Once you can read that folder, most theme problems become easier to name.
- GTK
- Theming
- 8 min read
A GTK theme is not a picture of a window. It is a set of rules that tell the toolkit how to draw a window, a button, an entry, a menu, and the focus ring that follows the keyboard. The rules are written in a style language, and the pictures are assets that the rules point to. A useful theme keeps those two parts in step.
What a theme actually is
At the top level, a theme folder has a name and a small metadata file. The metadata tells the desktop which toolkit versions the theme supports and which variants it offers, such as a light and a dark surface. If the metadata is wrong, the theme may sit in a folder and never appear in the settings list. That is why a theme can be installed and still look absent.
The folder map
A typical theme separates the toolkit versions because the style language changes between them. A theme built for an older toolkit may load in a newer one and still miss a widget that did not exist when it was written. Read the project page for the versions the author tested. Do not assume that a folder name is a promise.
- Metadata. The small file that names the theme and lists its variants.
- Style rules. The file that sets color, spacing, borders, and radius for each widget.
- Assets. The images used for window controls, arrows, check marks, and other shapes that are not drawn by a rule.
- Window controls. The close, minimize, and maximize art, which often has its own folder and its own naming pattern.
The files that matter most
The style rules carry the personality of the theme. Color values decide the surface, the text, the accent, and the focus ring. Spacing values decide whether a menu feels tight or calm. Border radius and shadow values decide whether a window feels flat or soft. A single color change can make a label unreadable, so change one value at a time and look at the result in more than one window.
Assets matter when a rule points to a shape that is missing. A missing arrow may show as a blank square. A missing check mark may show as nothing at all. If one control looks wrong while the rest of the theme looks fine, check the asset folder before you rewrite the style file.
Start with a copy
Copy the theme into your home folder instead of a system path. A home folder copy is easy to remove and easy to compare with the original. Keep the archive you downloaded beside the extracted folder so you can return to a clean copy. If the project ships a license file, keep that too; it is part of the work.
A second account gives you a clean session and a way back if the theme hides a menu or a dialog. Test there before you change the account you use every day.
Test with three windows
A theme that looks right in a file manager can fail in a settings window. Test at least three kinds of window: a file manager with a sidebar, a settings window with a list and a switch, and a dialog with a text entry and a dropdown. Then use the keyboard only. Tab through the controls and watch the focus ring. If the ring disappears on a dark surface, the theme has a contrast problem, not a rendering bug.
When a theme half works
Most partial failures fall into four groups. The theme targets a different toolkit version. The desktop cached an older style. An asset is missing or misnamed. The icon theme is from a different set, so the shapes do not share a grid. Work through those four before you edit a file. The answer is often a version check or a fresh session, not a rewrite.
License and credit
A theme is creative work. Read the license before you repackage it, change its name, or include it in a release. Keep the author's name and the source page in your notes. If you build on someone else's shapes, ask for permission and say what you changed. A clear credit line is part of a finished theme.
A short checklist
- Read the metadata and confirm the toolkit versions.
- Copy the theme into your home folder and keep the archive.
- Test on a second account before your daily account.
- Check a file manager, a settings window, and a dialog.
- Tab through the controls and confirm the focus ring.
- Read the license and keep the credit line.
Further reading
The GTK documentation covers the style language and the widget names a theme can target. The icon theme specification explains the folder and naming rules behind the icons that sit beside a theme. GNOME Look is a large shelf for comparing finished work, and Inkscape is useful when you need to redraw an asset at a clean size.