##(see the SpecSpec for an explanation)
||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents()>>||

While most of the Unity look tries to adapt to the current user wallpaper, there are some aspects of unity that can be themed.

== Decorations ==

Until 13.10 unity supported the metacity theming engine, through the compiz native `gtk-window-decorator`, however this system is quite old right now, and has never been ported to gtk3 to get better theming capabilities and support gtk-css theming (hey, no anti-aliased rounded corners!). Also its architecture was really quite complex and caused things such as the normal resizing to be much slower.

So, as part of the cleanup for '''Ubuntu 14.04''', we defined a completely new theming system based on [[https://developer.gnome.org/gtk3/stable/GtkStyleContext.html|GtkStyleContext]], that uses CSS for pretty much everything.

In order to theme the window decorations (examples on [[https://code.launchpad.net/ubuntu-themes/|ubuntu-themes branch]]), you basically need to define a style for the `UnityDecoration` "fake" widget and for the classes `top`, `left`, `right` and `bottom` in your '''Gtk3''' theme.

=== Properties ===
The `UnityDecoration` widget also supports some custom properties that we use to define some decoration-related parameters; you can see the ones currently supported here:

{{{#!highlight css
UnityDecoration {
    /* Border properties (top, right, bottom, left) */
    -UnityDecoration-extents: 28px 1px 1px 1px; /* the size of the decorations  */
    -UnityDecoration-input-extents: 10px; /* the extra size of the input areas */

    /* Shadows settings */
    -UnityDecoration-shadow-offset-x: 1px; /* Size property, the shadow x offset */
    -UnityDecoration-shadow-offset-y: 1px; /* Size property, the shadow y offset */
    -UnityDecoration-active-shadow-color: rgba (0, 0, 0, 0.647); /* Color property, active window shadow color */
    -UnityDecoration-active-shadow-radius: 8px; /* Size property, active window shadow radius */
    -UnityDecoration-inactive-shadow-color: rgba (0, 0, 0, 0.647); /* Color property, inactive windows shadow color */
    -UnityDecoration-inactive-shadow-radius: 5px; /* Size property, inactive windows shadow radius */

    /* Glow applied to the selected scaled window */
    -UnityDecoration-glow-size: 10px; /* Size property, size of glow */
    -UnityDecoration-glow-color: rgb (221, 72, 20); /* Color property of the glow */

    /* Title settings */
    -UnityDecoration-title-indent: 10px; /* Size property, left indent of the title */
    -UnityDecoration-title-fade: 35px; /* Size property, space of the title that can be faded */
    -UnityDecoration-title-alignment: 0.0; /* Float from 0.0 to 1.0, to align the title */
}
}}}

=== Examples ===

Except these "special" per-theme settings, all the rest of the theming can be done with standard [[https://developer.gnome.org/gtk3/stable/GtkCssProvider.html|GtkCss]]. You only need to define a theme for each selector, keeping in mind that the ''normal state'' covers the '''active window''', while the `backdrop` state will match the '''inactive windows'''.<<BR>>
For example:

{{{#!highlight css
/* This will theme the top decoration, so the whole space above the window */
UnityDecoration.top {
    border: 1px solid shade (@bg_color, 0.5);
    border-bottom-width: 0;
    border-radius: 8px 8px 0 0; /* Corner radius, only the top ones should be */
    padding: 1px 8px 0 8px; /* This padding will be applied to the content of the top layout */
    background-color: shade (@dark_bg_color, 1.5); /* Decoration background */
    color: @dark_fg_color; /* The foreground color will be used to paint the text */
    text-shadow: 1px 0 #333, -1px 0 #333, 0 1px #333, 0 -1px #333;
}

/* Top decoration for inactive windows */
UnityDecoration.top:backdrop {
    border: 1px solid @dark_bg_color;
    border-bottom-width: 0;
    background-color: shade (#474642, 0.92);
    color: #807d78;
}

/* Left decoration, it themes only the space at the left of the window */
UnityDecoration.left,
/* Right decoration, it themes only the space at the right of the window */
UnityDecoration.right,
/* Bottom decoration, it themes all the space below the window */
UnityDecoration.bottom {
    background-color: shade (@bg_color, 0.5);
}

/* Left, right and bottom decorations themes for inactive windows */
UnityDecoration.left:backdrop,
UnityDecoration.right:backdrop,
UnityDecoration.bottom:backdrop {
    background-color: shade (@bg_color, 0.3);
}
}}}

=== Window Buttons ===

Finally, for the '''window buttons''', you should provide these pixmaps in order to cover all the types and possible widget states.<<BR>>
These pixmaps we'll be used by both the Unity decorations and the Unity panel. We have a policy were we try to load SVGs first, then pngs:

{{{
$THEME_PATH/unity/close.{svg, png}
$THEME_PATH/unity/close_focused_normal.{svg, png}
$THEME_PATH/unity/close_focused_prelight.{svg, png}
$THEME_PATH/unity/close_focused_pressed.{svg, png}
$THEME_PATH/unity/close_unfocused.{svg, png}
$THEME_PATH/unity/close_unfocused_prelight.{svg, png}
$THEME_PATH/unity/close_unfocused_pressed.{svg, png}
$THEME_PATH/unity/maximize.{svg, png}
$THEME_PATH/unity/maximize_focused_normal.{svg, png}
$THEME_PATH/unity/maximize_focused_prelight.{svg, png}
$THEME_PATH/unity/maximize_focused_pressed.{svg, png}
$THEME_PATH/unity/maximize_unfocused.{svg, png}
$THEME_PATH/unity/maximize_unfocused_prelight.{svg, png}
$THEME_PATH/unity/maximize_unfocused_pressed.{svg, png}
$THEME_PATH/unity/minimize.{svg, png}
$THEME_PATH/unity/minimize_focused_normal.{svg, png}
$THEME_PATH/unity/minimize_focused_prelight.{svg, png}
$THEME_PATH/unity/minimize_focused_pressed.{svg, png}
$THEME_PATH/unity/minimize_unfocused.{svg, png}
$THEME_PATH/unity/minimize_unfocused_prelight.{svg, png}
$THEME_PATH/unity/minimize_unfocused_pressed.{svg, png}
$THEME_PATH/unity/unmaximize.{svg, png}
$THEME_PATH/unity/unmaximize_focused_normal.{svg, png}
$THEME_PATH/unity/unmaximize_focused_prelight.{svg, png}
$THEME_PATH/unity/unmaximize_focused_pressed.{svg, png}
$THEME_PATH/unity/unmaximize_unfocused.{svg, png}
$THEME_PATH/unity/unmaximize_unfocused_prelight.{svg, png}
$THEME_PATH/unity/unmaximize_unfocused_pressed.{svg, png}
}}}

The ''dash buttons'' are themable as well using these names:
{{{
$THEME_PATH/unity/close_dash.{svg, png}
$THEME_PATH/unity/close_dash_disabled.{svg, png}
$THEME_PATH/unity/close_dash_prelight.{svg, png}
$THEME_PATH/unity/close_dash_pressed.{svg, png}
$THEME_PATH/unity/maximize_dash.{svg, png}
$THEME_PATH/unity/maximize_dash_disabled.{svg, png}
$THEME_PATH/unity/maximize_dash_prelight.{svg, png}
$THEME_PATH/unity/maximize_dash_pressed.{svg, png}
$THEME_PATH/unity/minimize_dash.{svg, png}
$THEME_PATH/unity/minimize_dash_disabled.{svg, png}
$THEME_PATH/unity/minimize_dash_prelight.{svg, png}
$THEME_PATH/unity/minimize_dash_pressed.{svg, png}
$THEME_PATH/unity/unmaximize_dash.{svg, png}
$THEME_PATH/unity/unmaximize_dash_disabled.{svg, png}
$THEME_PATH/unity/unmaximize_dash_prelight.{svg, png}
$THEME_PATH/unity/unmaximize_dash_pressed.{svg, png}
}}}

In case you don't have specified a theme for UnityDecorations in your theme, we generate window buttons using cairo (using the foreground color for non-close buttons, and red for close one) and we try to fallback to `gnome-panel` and/or `gnome-headerbar` themes.<<BR>>
So, although the result won't be as nice as it might be with a native theme, it will be still usable.<<BR>>
Keep in mind, when writing an UnityDecoration theme, that if you've defined a theme for `gnome-panel` and/or `gnome-headerbar`, they might clash with this one (that has priority, though), so in case of weird behavior, just make sure you override their values (i.e. using something such as `background-image: none;`).

=== Locally Integrated Menus ===

Of course menu items embedded into the decorations can be themed as well, adding the `.menuitem` class, such as:

{{{#!highlight css
UnityDecoration.menuitem {
    color: #dd4814;
}
}}}

=== Theming tools ===

To make easier for theme writers to check the results of their CSS, I've written a simple vala program that draws a decoration (using the current theme) into an image. You can [[http://pastebin.ubuntu.com/6808987/|grab it here]] to see the results of your theming work without applying this directly to unity.

== Unity Panel ==

Like the decorations, the panel is decorated with Gtk3 css themes, so all you need is defining a style for the `UnityPanelWidget` widget and with class `.unity-panel`

{{{#!highlight css
UnityPanelWidget,
.unity-panel {
    background-color: shade (@dark_bg_color, 1.5);
    color: @dark_fg_color; /* Text color */
}
}}}

If you only want to modify the panel title you can use this selector:

{{{#!highlight css
.unity-panel.panel-title {
    color: shade (@dark_fg_color, 1.5); /* Text color */
}
}}}

For menu-items (and indicators) you can use instead:
{{{#!highlight css
.unity-panel.menuitem {
    color: shade (@dark_fg_color, 1.2); /* Labels color */
}
}}}

== Panel Menu Items ==

Also menu items are themed using Gtk3 css:

{{{#!highlight css
.unity-panel.menuitem,
.unity-panel .menuitem {
    border-width: 1px 1px 0 1px;
    icon-shadow: 0 -1px shade (@dark_bg_color, 0.7);
}

.unity-panel.menubar:backdrop,
.unity-panel .menubar *:backdrop {
    color: @backdrop_dark_fg_color;
}

.unity-panel.menubar.menuitem:hover,
.unity-panel.menubar .menuitem *:hover {
    background-color: red;
}
}}}

== Launcher/Switcher Icons ==

The launcher and switcher are automagically coloured using the average background color (unless you don't force a color in ccsm), but still you can theme the '''icon tiles''', providing the proper '''''textures''''' to make them look in the way you prefer.

First of all, we currently support ''two sizes'' for each texture (`small`, used when icons have a tile < 100px, `big` otherwise); the icons can be both SVGs or PNGs (althought the first are preferred to scale better in HiDPI displays).<<BR>>
Also, they will be painted following the order below:

These textures will be drawn '''before''' the actual ''icon pixbuf'':
{{{
$THEME_PATH/unity/launcher_icon_shadow_{62, 200}.{svg, png} /* icon shadow, not colorified */
$THEME_PATH/unity/launcher_icon_back_{54, 150}.{svg, png} /* icon background, it can be colorified */
$THEME_PATH/unity/launcher_icon_selected_back_{54, 150}.{svg, png} /* icon background on key navigation */
$THEME_PATH/unity/launcher_icon_edge_{54, 150}.{svg, png} /* edges of the icon, generally not colorified */
}}}
While these textures will be drawn '''after''' the actual ''icon pixbuf'':
{{{
$THEME_PATH/unity/launcher_icon_shine_{54, 150}.{svg, png} /* icon shine, not colorified */
$THEME_PATH/unity/launcher_icon_glow_{62, 200}.{svg, png} /* icon glow, it can be colorified */
}}}

These are the '''icon emblems''' used to draw the ''progress bar'' over an icon:
{{{
$THEME_PATH/unity/progress_bar_trough.{svg, png}
$THEME_PATH/unity/progress_bar_fill.{svg, png}
}}}

And these are the '''icon markers''' that can be drawn on left or right of the icons, depending on their state:
{{{
$THEME_PATH/unity/launcher_arrow_ltr_{19, 37}.{svg, png} /* the marker drawn on running apps */
$THEME_PATH/unity/launcher_arrow_outline_ltr_{19, 37}.{svg, png} /* the marker drawn running apps on different WS/monitor */
$THEME_PATH/unity/launcher_pip_ltr_{19, 37}.{svg, png} /* the marker drawn on apps with multiple windows (can be repeated) */
$THEME_PATH/unity/launcher_arrow_rtl_{19, 37}.{svg, png} /* the marker drawn on the focused app */
}}}

The '''BFB (Big Fat Button) icon''' (starting from Ubuntu 16.04) can be themed as well by adding an icon in the path below. We ask you to keep the [[http://design.ubuntu.com/brand/ubuntu-logo|Circle of Friends]] logo in your implementation, though.
{{{
$THEME_PATH/unity/launcher_bfb.{svg, png}
}}}

'''Make sure you respect these sizes''', (and paddings for markers) or the results might not be the ones you expect.

== Dash ==

Dash widgets can be slightly themed, by editing the `dash-widgets.json` file. The file is located in this position:

{{{
$THEME_PATH/unity/dash-widgets.json
}}}

== Windows Force Quit dialog ==
You can select the unity windows force-quit dialogs by using the `.unity-force-quit` class or just the `SheetStyleDialog` (for gtk+ < 3.20) and `sheet-style-dialog` (for gtk+ >= 3.20) generic name:
{{{#!highlight css
SheetStyleDialog.unity-force-quit, sheet-style-dialog.unity-force-quit {
    background-color: #dd4814;
}
}}}

It will instead use these icons for the ''close button'':

{{{
$THEME_PATH/unity/sheet_style_close_focused.{svg, png}
$THEME_PATH/unity/sheet_style_close_focused_prelight.{svg, png}
$THEME_PATH/unity/sheet_style_close_focused_pressed.{svg, png}
}}}