[libadwaita/wip/exalm/style-docs: 1/6] docs: Add named colors and style class docs
- From: Alexander Mikhaylenko <alexm src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libadwaita/wip/exalm/style-docs: 1/6] docs: Add named colors and style class docs
- Date: Wed, 15 Dec 2021 13:19:15 +0000 (UTC)
commit d0d3ff64cda1979c2c6989808432f836776033bd
Author: Alexander Mikhaylenko <alexm gnome org>
Date: Wed Dec 15 17:37:53 2021 +0500
docs: Add named colors and style class docs
doc/libadwaita.toml.in | 2 +
doc/meson.build | 2 +
doc/named-colors.md | 758 +++++++++++++++++++++++++++++++++++++++++++++++
doc/style-classes.md | 410 +++++++++++++++++++++++++
doc/tools/gen-palette.py | 47 +++
5 files changed, 1219 insertions(+)
---
diff --git a/doc/libadwaita.toml.in b/doc/libadwaita.toml.in
index 3dd101f9..1d40e69f 100644
--- a/doc/libadwaita.toml.in
+++ b/doc/libadwaita.toml.in
@@ -41,6 +41,8 @@ content_files = [
"build-howto.md",
"migrating-between-development-versions.md",
"migrating-libhandy-1-4-to-libadwaita.md",
+ "named-colors.md",
+ "style-classes.md",
"visual-index.md",
]
content_images = [
diff --git a/doc/meson.build b/doc/meson.build
index e27343ba..b5ae25eb 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -4,6 +4,8 @@ expand_content_md_files = [
'build-howto.md',
'migrating-between-development-versions.md',
'migrating-libhandy-1-4-to-libadwaita.md',
+ 'named-colors.md',
+ 'style-classes.md',
'visual-index.md',
]
diff --git a/doc/named-colors.md b/doc/named-colors.md
new file mode 100644
index 00000000..9c4e3aa9
--- /dev/null
+++ b/doc/named-colors.md
@@ -0,0 +1,758 @@
+Title: Named Colors
+Slug: named-colors
+
+<style type="text/css" rel="stylesheet">
+.color-pill {
+ width: 20px;
+ height: 20px;
+ border-radius: 100%;
+ background-clip: padding-box;
+ border: 1px solid transparent;
+}
+
+.color-pill.light {
+ border-color: rgba(0, 0, 0, .1);
+}
+
+.color-pill.dark {
+ border-color: rgba(255, 255, 255, .2);
+}
+
+.color-pill.light.dark {
+ border-color: rgba(200, 200, 200, .35);
+}
+
+.numeric {
+ font-variant-numeric: tabular-nums;
+}
+</style>
+
+# Named Colors
+
+The Adwaita stylesheet provides a number of predefined colors that can be used
+from applications.
+
+## UI Colors
+
+These colors are used throughout the UI. They can differ between the light and
+dark styles.
+
+Many colors are grouped as background/foreground pairs. These colors are always
+meant to be used together as the background and text color, for example:
+
+```css
+my-widget {
+ background-color: @accent_bg_color;
+ color: @accent_fg_color;
+}
+```
+
+Some colors also have standalone versions. They are similar to the background
+version, but provide better contrast when used as foreground colors on top of a
+neutral background - for example, colorful text in a window.
+
+```css
+my-widget {
+ color: @accent_color;
+}
+```
+
+Standalone colors are typically darker than the corresponding background color
+for the light style, and lighter than background for the dark style.
+
+Applications can override any of these colors by re-declaring them, for example:
+
+```css
+@define-color accent_color #c01c28;
+@define-color accent_bg_color #e01b24;
+```
+
+### Accent Colors
+
+The accent color is used across many different widgets, often to indicate that a
+widget is important, interactive, or currently active. Try to avoid using it on
+large surfaces, or on too many items on the same view.
+
+The [`.accent`](style-classes.html#colors) style class allows to use it for
+widgets such as [class@Gtk.Label].
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@accent_color</tt></td>
+ <td><div class="color-pill" style="background-color: #1c71d8"/></td>
+ <td><tt>#1c71d8</tt></td>
+ <td><div class="color-pill" style="background-color: #78aeed"/></td>
+ <td><tt>#78aeed</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@accent_bg_color</tt></td>
+ <td><div class="color-pill" style="background-color: #3584e4"/></td>
+ <td><tt>#3584e4</tt></td>
+ <td><div class="color-pill" style="background-color: #3584e4"/></td>
+ <td><tt>#3584e4</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@accent_fg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+</table>
+
+### Destructive Colors
+
+The destructive color indicates a dangerous action, such as deleting a file.
+It's used by [class@Gtk.Button] containing the
+[`.destructive-action`](style-classes.html#destructive-action) style class.
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@destructive_color</tt></td>
+ <td><div class="color-pill" style="background-color: #c01c28"/></td>
+ <td><tt>#c01c28</tt></td>
+ <td><div class="color-pill" style="background-color: #ff7b63"/></td>
+ <td><tt>#ff7b63</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@destructive_bg_color</tt></td>
+ <td><div class="color-pill" style="background-color: #e01b24"/></td>
+ <td><tt>#e01b24</tt></td>
+ <td><div class="color-pill" style="background-color: #c01c28"/></td>
+ <td><tt>#c01c28</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@destructive_fg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+</table>
+
+### Success Colors
+
+This color is used with the [`.success`](style-classes.html#colors) style class,
+or in a [class@Gtk.LevelBar] with the `GTK_LEVEL_BAR_OFFSET_HIGH` offset.
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@success_color</tt></td>
+ <td><div class="color-pill" style="background-color: #26a269"/></td>
+ <td><tt>#26a269</tt></td>
+ <td><div class="color-pill" style="background-color: #8ff0a4"/></td>
+ <td><tt>#8ff0a4</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@success_bg_color</tt></td>
+ <td><div class="color-pill" style="background-color: #2ec27e"/></td>
+ <td><tt>#2ec27e</tt></td>
+ <td><div class="color-pill" style="background-color: #26a269"/></td>
+ <td><tt>#26a269</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@success_fg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+</table>
+
+### Warning Colors
+
+This color is used with the [`.warning`](style-classes.html#colors) style class,
+or in a [class@Gtk.LevelBar] with the `GTK_LEVEL_BAR_OFFSET_LOW` offset.
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@warning_color</tt></td>
+ <td><div class="color-pill" style="background-color: #ae7b03"/></td>
+ <td><tt>#ae7b03</tt></td>
+ <td><div class="color-pill" style="background-color: #f8e45c"/></td>
+ <td><tt>#f8e45c</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@warning_bg_color</tt></td>
+ <td><div class="color-pill" style="background-color: #e5a50a"/></td>
+ <td><tt>#e5a50a</tt></td>
+ <td><div class="color-pill" style="background-color: #cd9309"/></td>
+ <td><tt>#cd9309</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@warning_fg_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.8)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.8)</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.8)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.8)</tt></td>
+ </tr>
+</table>
+
+### Error Colors
+
+This color is used with the [`.error`](style-classes.html#colors) style class.
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@error_color</tt></td>
+ <td><div class="color-pill" style="background-color: #c01c28"/></td>
+ <td><tt>#c01c28</tt></td>
+ <td><div class="color-pill" style="background-color: #ff7b63"/></td>
+ <td><tt>#ff7b63</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@error_bg_color</tt></td>
+ <td><div class="color-pill" style="background-color: #e01b24"/></td>
+ <td><tt>#e01b24</tt></td>
+ <td><div class="color-pill" style="background-color: #c01c28"/></td>
+ <td><tt>#c01c28</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@error_fg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+</table>
+
+### Window Colors
+
+These colors are used on [class@Gtk.Window], as well as with the
+[`.background`](style-classes.html#background) style class.
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@window_bg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #fafafa"/></td>
+ <td><tt>#fafafa</tt></td>
+ <td><div class="color-pill dark" style="background-color: #242424"/></td>
+ <td><tt>#242424</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@window_fg_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.8)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.8)</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+</table>
+
+### View Colors
+
+These colors are used in a variety of widgets such as [class@Gtk.TextView], as
+well as with the [`.view`](style-classes.html#view) style class.
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@view_bg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill dark" style="background-color: #1e1e1e"/></td>
+ <td><tt>#1e1e1e</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@view_fg_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: #000000"/></td>
+ <td><tt>#000000</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+</table>
+
+### Header Bar Colors
+
+These colors are used for [class@Gtk.HeaderBar], as well as widgets that are
+meant to be visually attached to it, such as [class@Gtk.SearchBar] or
+[class@Adw.TabBar], unless they have the
+[`.inline`](style-classes.html#inline-tab-bars-search-bars) style class.
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@headerbar_bg_color</tt></td>
+ <td><div class="color-pill" style="background-color: #ebebeb"/></td>
+ <td><tt>#ebebeb</tt></td>
+ <td><div class="color-pill dark" style="background-color: #303030"/></td>
+ <td><tt>#303030</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@headerbar_fg_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.8)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.8)</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@headerbar_border_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.8)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.8)</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@headerbar_backdrop_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #fafafa"/></td>
+ <td><tt>#fafafa</tt></td>
+ <td><div class="color-pill dark" style="background-color: #242424"/></td>
+ <td><tt>#242424</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@headerbar_shade_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.07)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.07)</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.36)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.36)</tt></td>
+ </tr>
+</table>
+
+The <code>@headerbar_border_color</code> color has the same default values
+as <code>@headerbar_fg_color</code>, but doesn't change along with it. This
+can be useful if a light window has a dark header bar with light text; in this
+case it may be desirable to keep the border dark.
+
+The <code>@headerbar_backdrop_color</code> color is used instead of
+<code>@headerbar_bg_color</code> when the window is not focused. By default
+it's an alias of [<code>@window_bg_color</code>](#window-colors) and changes
+together with it. When overriding header bar colors, make sure to set it to a
+value matching your <code>@headerbar_bg_color</code>.
+
+The <code>@headerbar_shade_color</code> color is used by [class@Adw.TabBar]
+to provide a visible darkening for inactive tabs and an overflow shadow. This
+color should always be transparentized black, with the opacity adjusted to be
+well visible on top of <code>@headerbar_bg_color</code>.
+
+### Card Colors
+
+These colors are used for
+[cards and boxed lists](style-classes.html#boxed-lists-cards).
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@card_bg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill light dark" style="background-color: rgba(255, 255, 255, 0.08)"/></td>
+ <td><tt>rgba(255, 255, 255, 0.08)</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@card_fg_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.8)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.8)</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@card_shade_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.07)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.07)</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.36)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.36)</tt></td>
+ </tr>
+</table>
+
+The card styles use a shadow to separate the card from the window background.
+The <code>@card_shade_color</code> color is used by this shadow. This color
+should always be transparentized black, with the opacity tuned to be well
+visible on top of [<code>@window_bg_color</code>](#window-colors).
+
+### Popover Colors
+
+These colors are used for [class@Gtk.Popover].
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@popover_bg_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill" style="background-color: #383838"/></td>
+ <td><tt>#383838</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@popover_fg_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.8)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.8)</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+</table>
+
+### Miscellaneous Colors
+
+<table>
+ <tr>
+ <th>Name</th>
+ <th/>
+ <th>Light</th>
+ <th/>
+ <th>Dark</th>
+ </tr>
+ <tr>
+ <td><tt>@shade_color</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.07)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.07)</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.36)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.36)</tt></td>
+ </tr>
+ <tr>
+ <td><tt>@scrollbar_outline_color</tt></td>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>#ffffff</tt></td>
+ <td><div class="color-pill dark" style="background-color: rgba(0, 0, 0, 0.5)"/></td>
+ <td><tt>rgba(0, 0, 0, 0.5)</tt></td>
+ </tr>
+</table>
+
+The <code>@shade_color</code> color is used by [class@Adw.TabBar] with the
+[`.inline`](style-classes.html#inline-tab-bars-search-bars) style class, as well
+as the transitions in [class@Adw.Leaflet] and [class Adw Flap]. This color
+should always be transparentized black, with the opacity tuned to be well
+visible on top of <code>@window_bg_color</code>.
+
+The <code>@scrollbar_outline_color</code> color is used by
+[class@Gtk.Scrollbar] to ensure that overlay scrollbars are visible regardless
+of the content color. It should always be the opposite of the scrollbar color -
+light with a dark scrollbar and dark with a light scrollbar.
+
+## Helper Colors
+
+The following colors are derived from the current foreground color
+(`currentColor`) and change between regular and high contrast modes. They should
+be used to support the high contrast mode automatically.
+
+Name | Regular | High contrast
+--------------------- | ---------------------------------- | ---------------------------------
+<tt>@borders</tt> | <tt>alpha(currentColor, 0.15)</tt> | <tt>alpha(currentColor, 0.5)</tt>
+
+## Palette Colors
+
+The stylesheet provides the full GNOME color palette as the following set of
+named colors:
+
+<!-- Generated with gen-palette.py -->
+<table>
+ <tr>
+ <th></th>
+ <th>Name</th>
+ <th>Value</th>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #99c1f1"/></td>
+ <td><tt>@blue_1</tt></td>
+ <td><tt>#99c1f1</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #62a0ea"/></td>
+ <td><tt>@blue_2</tt></td>
+ <td><tt>#62a0ea</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #3584e4"/></td>
+ <td><tt>@blue_3</tt></td>
+ <td><tt>#3584e4</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #1c71d8"/></td>
+ <td><tt>@blue_4</tt></td>
+ <td><tt>#1c71d8</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #1a5fb4"/></td>
+ <td><tt>@blue_5</tt></td>
+ <td><tt>#1a5fb4</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #8ff0a4"/></td>
+ <td><tt>@green_1</tt></td>
+ <td><tt>#8ff0a4</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #57e389"/></td>
+ <td><tt>@green_2</tt></td>
+ <td><tt>#57e389</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #33d17a"/></td>
+ <td><tt>@green_3</tt></td>
+ <td><tt>#33d17a</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #2ec27e"/></td>
+ <td><tt>@green_4</tt></td>
+ <td><tt>#2ec27e</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #26a269"/></td>
+ <td><tt>@green_5</tt></td>
+ <td><tt>#26a269</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #f9f06b"/></td>
+ <td><tt>@yellow_1</tt></td>
+ <td><tt>#f9f06b</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #f8e45c"/></td>
+ <td><tt>@yellow_2</tt></td>
+ <td><tt>#f8e45c</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #f6d32d"/></td>
+ <td><tt>@yellow_3</tt></td>
+ <td><tt>#f6d32d</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #f5c211"/></td>
+ <td><tt>@yellow_4</tt></td>
+ <td><tt>#f5c211</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #e5a50a"/></td>
+ <td><tt>@yellow_5</tt></td>
+ <td><tt>#e5a50a</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #ffbe6f"/></td>
+ <td><tt>@orange_1</tt></td>
+ <td><tt>#ffbe6f</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #ffa348"/></td>
+ <td><tt>@orange_2</tt></td>
+ <td><tt>#ffa348</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #ff7800"/></td>
+ <td><tt>@orange_3</tt></td>
+ <td><tt>#ff7800</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #e66100"/></td>
+ <td><tt>@orange_4</tt></td>
+ <td><tt>#e66100</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #c64600"/></td>
+ <td><tt>@orange_5</tt></td>
+ <td><tt>#c64600</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #f66151"/></td>
+ <td><tt>@red_1</tt></td>
+ <td><tt>#f66151</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #ed333b"/></td>
+ <td><tt>@red_2</tt></td>
+ <td><tt>#ed333b</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #e01b24"/></td>
+ <td><tt>@red_3</tt></td>
+ <td><tt>#e01b24</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #c01c28"/></td>
+ <td><tt>@red_4</tt></td>
+ <td><tt>#c01c28</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #a51d2d"/></td>
+ <td><tt>@red_5</tt></td>
+ <td><tt>#a51d2d</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #dc8add"/></td>
+ <td><tt>@purple_1</tt></td>
+ <td><tt>#dc8add</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #c061cb"/></td>
+ <td><tt>@purple_2</tt></td>
+ <td><tt>#c061cb</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #9141ac"/></td>
+ <td><tt>@purple_3</tt></td>
+ <td><tt>#9141ac</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #813d9c"/></td>
+ <td><tt>@purple_4</tt></td>
+ <td><tt>#813d9c</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #613583"/></td>
+ <td><tt>@purple_5</tt></td>
+ <td><tt>#613583</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #cdab8f"/></td>
+ <td><tt>@brown_1</tt></td>
+ <td><tt>#cdab8f</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #b5835a"/></td>
+ <td><tt>@brown_2</tt></td>
+ <td><tt>#b5835a</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #986a44"/></td>
+ <td><tt>@brown_3</tt></td>
+ <td><tt>#986a44</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #865e3c"/></td>
+ <td><tt>@brown_4</tt></td>
+ <td><tt>#865e3c</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #63452c"/></td>
+ <td><tt>@brown_5</tt></td>
+ <td><tt>#63452c</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill light" style="background-color: #ffffff"/></td>
+ <td><tt>@light_1</tt></td>
+ <td><tt>#ffffff</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill light" style="background-color: #f6f5f4"/></td>
+ <td><tt>@light_2</tt></td>
+ <td><tt>#f6f5f4</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #deddda"/></td>
+ <td><tt>@light_3</tt></td>
+ <td><tt>#deddda</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #c0bfbc"/></td>
+ <td><tt>@light_4</tt></td>
+ <td><tt>#c0bfbc</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #9a9996"/></td>
+ <td><tt>@light_5</tt></td>
+ <td><tt>#9a9996</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #77767b"/></td>
+ <td><tt>@dark_1</tt></td>
+ <td><tt>#77767b</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #5e5c64"/></td>
+ <td><tt>@dark_2</tt></td>
+ <td><tt>#5e5c64</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill" style="background-color: #3d3846"/></td>
+ <td><tt>@dark_3</tt></td>
+ <td><tt>#3d3846</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill dark" style="background-color: #241f31"/></td>
+ <td><tt>@dark_4</tt></td>
+ <td><tt>#241f31</tt></td>
+ </tr>
+ <tr>
+ <td><div class="color-pill dark" style="background-color: #000000"/></td>
+ <td><tt>@dark_5</tt></td>
+ <td><tt>#000000</tt></td>
+ </tr>
+</table>
+
+## Compatibility Colors
+
+A number of colors has been available in Adwaita in GTK3. They are aliases of
+UI colors or otherwise derived from them:
+
+Name | Value
+----------------------------------------------- | -----------------------------
+<tt>@theme_bg_color</tt> | [<tt>@window_bg_color</tt>](#window-colors)
+<tt>@theme_fg_color</tt> | [<tt>@window_fg_color</tt>](#window-colors)
+<tt>@theme_base_color</tt> | [<tt>@view_bg_color</tt>](#view-colors)
+<tt>@theme_text_color</tt> | [<tt>@view_fg_color</tt>](#view-colors)
+<tt>@theme_selected_bg_color</tt> | [<tt>@accent_bg_color</tt>](#accent-colors)
+<tt>@theme_selected_fg_color</tt> | [<tt>@accent_fg_color</tt>](#accent-colors)
+<tt>@insensitive_bg_color</tt> | <tt>mix(@window_bg_color, @view_bg_color, 0.4)</tt>
+<tt>@insensitive_fg_color</tt> | <tt>alpha(@window_fg_color, 0.5)</tt>
+<tt>@insensitive_base_color</tt> | [<tt>@view_bg_color</tt>](#view-colors)
+<tt>@theme_unfocused_bg_color</tt> | [<tt>@window_bg_color</tt>](#window-colors)
+<tt>@theme_unfocused_fg_color</tt> | [<tt>@window_fg_color</tt>](#window-colors)
+<tt>@theme_unfocused_base_color</tt> | [<tt>@view_bg_color</tt>](#view-colors)
+<tt>@theme_unfocused_text_color</tt> | [<tt>@view_fg_color</tt>](#view-colors)
+<tt>@theme_unfocused_selected_bg_color</tt> | [<tt>@accent_bg_color</tt>](#accent-colors)
+<tt>@theme_unfocused_selected_fg_color</tt> | [<tt>@accent_fg_color</tt>](#accent-colors)
+<tt>@unfocused_insensitive_color</tt> | <tt>@insensitive_bg_color</tt>
+<tt>@unfocused_borders</tt> | [<tt>@borders</tt>](#helper-colors)
diff --git a/doc/style-classes.md b/doc/style-classes.md
new file mode 100644
index 00000000..3dd4ce0f
--- /dev/null
+++ b/doc/style-classes.md
@@ -0,0 +1,410 @@
+Title: Style Classes
+Slug: style-classes
+
+# Style Classes
+
+The Adwaita stylesheet provides a number of style classes. They can be applied
+to widgets to change their appearance.
+
+## Buttons
+
+The following style classes can be applied to [class@Gtk.Button] to change its
+appearance.
+
+### Suggested Action
+
+The `.suggested-action` style class makes the button use accent colors. It can
+be used to denote important buttons, for example the affirmative button in an
+action dialog.
+
+Can be used in combination with [`.circular`](#circular) or [`.pill`](#pill).
+
+Can also be used with [class@Gtk.MenuButton] or [class@Adw.SplitButton].
+
+### Destructive Action
+
+The `.destructive-action` style class makes the button use destructive colors.
+It can be used to draw attention to the potentially damaging consequences of
+using a button. This style acts as a warning to the user.
+
+Can be used in combination with [`.circular`](#circular) or [`.pill`](#pill).
+
+Can also be used with [class@Gtk.MenuButton] or [class@Adw.SplitButton].
+
+### Flat
+
+The `.flat` style class makes the button use flat appearance, looking like a
+label or an icon until hovered.
+
+Button inside [toolbars and similar widgets](#toolbars) appear flat by default.
+
+Can be used in combination with [`.circular`](#circular) or [`.pill`](#pill).
+
+Can also be used with [class@Gtk.MenuButton] or [class@Adw.SplitButton].
+
+Can be managed via [property@Gtk.Button:has-frame] and
+[property@Gtk.MenuButton:has-frame].
+
+### Raised
+
+The `.raised` style class makes the button use regular appearance instead of
+the flat one.
+
+This style class is only useful inside [toolbars and similar widgets](#toolbars).
+
+Can be used in combination with [`.circular`](#circular) or [`.pill`](#pill).
+
+Can also be used with [class@Gtk.MenuButton] or [class@Adw.SplitButton].
+
+### Opaque
+
+The `.opaque` style class gives the button an opaque background. It's intended
+to be used together with custom styles that override `background-color` and
+`color`, to create buttons with an appearance similar to
+[`.suggested-action`](#suggested-action) and
+[`.destructive-action`](#destructive-action), but with custom colors.
+
+For example, `.suggested-action` and `.destructive-action` are equivalent to
+using the `.opaque` style
+class with the following CSS:
+
+```css
+#custom-suggested-action-button {
+ background-color: @accent_bg_color;
+ color: @accent_fg_color;
+}
+
+#custom-destructive-action-button {
+ background-color: @destructive_bg_color;
+ color: @destructive_fg_color;
+}
+```
+
+Can be used in combination with [`.circular`](#circular) or [`.pill`](#pill).
+
+Can also be used with [class@Gtk.MenuButton] or [class@Adw.SplitButton].
+
+### Circular
+
+The `.circular` style class makes the button round. It can be used with buttons
+containing icons or short labels (1-2 characters).
+
+Can be used in combination with [`.suggested-action`](#suggested-action),
+[`.destructive-action`](#destructive-action), [`.flat`](#flat),
+[`.raised`](#raised), [`.opaque`](#opaque) or [`.osd`](#overlay-buttons).
+
+Can also be used with [class@Gtk.MenuButton].
+
+### Pill
+
+The `.pill` style class makes the button appear as a pill. Pill buttons are
+often used on important standalone buttons, for example inside a
+[class@Adw.StatusPage].
+
+Can be used in combination with [`.suggested-action`](#suggested-action),
+[`.destructive-action`](#destructive-action), [`.flat`](#flat),
+[`.raised`](#raised), [`.opaque`](#opaque) or [`.osd`](#overlay-buttons).
+
+## Linked controls
+
+The `.linked` style class can be applied to a [class Gtk Box] to make its
+children appear as a single group. The box must have no spacing.
+
+The following widgets can be linked:
+
+* [class@Gtk.AppChooserButton]
+* [class@Gtk.Button]
+* [class@Gtk.Entry]
+* [class@Gtk.ColorButton]
+* [class@Gtk.ComboBox]
+* [class@Gtk.DropDown]
+* [class@Gtk.FontButton]
+* [class@Gtk.MenuButton]
+* [class@Gtk.PasswordEntry]
+* [class@Gtk.SearchEntry]
+* [class@Gtk.SpinButton]
+
+Linked styles will not work correctly for buttons with the following style
+classes:
+
+* [`.flat`](#flat)
+* [`.suggested-action`](#suggested-action)
+* [`.destructive-action`](#destructive-action)
+* [`.opaque`](#opaque)
+
+If a linked box is contained within a [toolbars or a similar widget](#toolbars),
+buttons inside it won't get the flat appearance.
+
+## Toolbars
+
+The `.toolbar` style class can be applied to a horizontal [class Gtk Box]. The
+same appearance is also used by [class@Gtk.HeaderBar], [class@Gtk.ActionBar] and
+[class@Gtk.SearchBar] automatically.
+
+It changes the appearance of buttons inside it to make them flat when possible,
+according to the following rules:
+
+The following buttons get flat appearance:
+
+* Icon-only buttons;
+* Buttons with an icon and a label (using [class@Adw.ButtonContent]);
+* Menu buttons containing an arrow;
+* [class@Adw.SplitButton];
+* Any other button with the [`.flat`](#flat) style class.
+
+The following buttons keep default appearance:
+
+* Text-only buttons;
+* Buttons with other content;
+* Buttons within widgets containing the [`.linked`](#linked-controls)` style
+ class;
+* Buttons with the [`.suggested-action`](#suggested-action) or
+ [`.destructive-action`](#destructive-action) style classes.
+* Buttons with the [`.raised`](#raised) style class.
+
+It also ensures 6px margins and spacing between widgets. The
+[`.spacer`](#spacers) style class can be useful to separate groups of widgets.
+
+Important: the [property@Gtk.Button:has-frame] property will **not** be set to
+`FALSE` when a button gets the flat appearance automatically. It also cannot be
+set to `TRUE` to make a button raised, the style class should be used directly
+instead.
+
+## Spacers
+
+The `.spacer` style class can be applied to a [class@Gtk.Separator] to make it
+appear invisible and act as whitespace. This can be useful with [toolbars and
+similar widgets](#toolbars) to separate groups of widgets from each other.
+
+## Dim Labels
+
+The `.dim-label` style class makes the widget it's applied to partially
+transparent.
+
+The level of transparency differs between regular and high contrast styles. As
+such, it's highly recommended to be used instead of changing opacity manually.
+
+## Typography Styles
+
+These style classes can be applied to any widgets, but are mostly used for
+[class@Gtk.Label] or other widgets that contain them.
+
+The `.large-title` style class makes text large and thin. It's the largest
+style, infrequently used for display headings in greeters or assistants. Should
+only be used in conjunction with large amounts of white space.
+
+The `.title-1`, `.title-2`, `.title-3`, `.title-4` classes provide four levels
+of title styles, indicating hierarchy. The specific use heavily depends on
+context. Generally, the larger styles are intended to be used in bigger views
+with plenty of whitespace around them.
+
+The `.heading` style class is the standard style for UI headings using the
+default text size, such as window titles or boxed list labels.
+
+The `.body` style class is the default text style.
+
+The `.caption-heading` and `.caption` style classes make text smaller. They
+are intended to be used to differentiate sub-text which accompanies text in
+the regular body style.
+
+The `.monospace` style class makes the widget use a monospace font. This can be
+useful when displaying code, logs or shell commands.
+
+The `.numeric` style class makes the widget use tabular figures. This is
+equivalent to using [struct@Pango.AttrFontFeatures] with `"tnum=1"` features.
+This style is useful in situations where multiple labels are vertically aligned,
+or when when displaying time, an operation progress or another number that can
+quickly change.
+
+## Colors
+
+The following style classes change widget colors:
+
+Class | Color
+----------------- | -------------------------------------------
+<tt>.accent</tt> | [accent color](named-colors.html#accent-colors)
+<tt>.success</tt> | [success color](named-colors.html#success-colors)
+<tt>.warning</tt> | [warning color](named-colors.html#warning-colors)
+<tt>.error</tt> | [error color](named-colors.html#error-colors)
+
+They can be applied to any widget.
+
+The `.error`, `.warning` and `.success` style classes can be applied to
+[class@Gtk.Entry]. In that case, they can be used to indicate input validation
+state.
+
+## Boxed Lists & Cards
+
+The `.boxed-list` style class can be applied to a [class@Gtk.ListBox] to make it
+a boxed list. The list box should have [property@Gtk.ListBox:selection-mode] set
+to `GTK_SELECTION_NONE`.
+
+The `.card` style class can be applied to any other widget to give it a similar
+appearance.
+
+If a widget with the `.card` style class also has the `.activatable` style
+class, it will also have hover and active states similar to an activatable row
+inside a boxed list.
+
+If the `.card` style class is applied to a [class@Gtk.Button], it will get these
+states automatically, without needing the `.activatable` class.
+
+## Sidebars
+
+The `.navigation-sidebar` style class can be applied to a [class@Gtk.ListBox]
+or [class@Gtk.ListView] to make it look like a sidebar: it makes the
+items rounded and padded and removes the default list background.
+
+When using it on a flap widget in an [class Adw Flap], the lack of background
+can be problematic. In that case, it can be used together with the
+[`.background`](#background) style class.
+
+## App Icons
+
+GNOME application icons require a shadow to be legible on light background. The
+`.icon-dropshadow` and `.lowres-icon` style classes provide it when used with
+[class@Gtk.Image].
+
+`.lowres-icon` should be used for 32×32 or smaller icons, and `.icon-dropshadow`
+should be used otherwise.
+
+## Selection Mode Check Buttons
+
+The `.selection-mode` style class can be added to a [class@Gtk.CheckButton] to
+give it a larger and round appearance. These check buttons are intended to be
+used for selecting items from a list or a grid.
+
+## OSD
+
+The `.osd` style class has a number of loosely related purposes depending on
+what widget it's applied to.
+
+Usually it makes the widget background dark and partially transparent, and
+makes its accent color white.
+
+However, it has different effects in a few specific cases.
+
+### Overlay Buttons
+
+When used with [class@Gtk.Button], it can be used to create large standalone
+buttons that overlap content, for example the previous/next page arrows in an
+image viewer. They appear dark and slightly larger than regular buttons.
+
+It can be used in combination with [`.circular`](#circular) or [`.pill`](#pill).
+
+### Floating Toolbars
+
+When used along with the [`.toolbar`](#toolbars) style class, it gives the
+box additional padding and round corners. This can be used to create floating
+toolbars, such video player controls.
+
+### Progress Bars
+
+When used with [class@Gtk.ProgressBar], it makes the progress bar thinner and
+removes its visible trough.
+
+OSD progress bars are intended to be used as [class@Gtk.Overlay] children,
+attached to the top of the window.
+
+## Background
+
+The `.background` style class can be used with any widget to give it the default
+[window](named-colors.html#window-colors) background and foreground colors.
+
+This can be useful when a widget needs an opaque background - for example, a
+flap child inside an [class Adw Flap].
+
+It's equivalent to using the following CSS:
+
+```css
+.background {
+ background-color: @window_bg_color;
+ color: @window_fg_color;
+}
+```
+
+## View
+
+The `.view` style class can be used with any widget to give it the default
+[view](named-colors.html#window-colors) background and foreground colors.
+
+It's equivalent to using the following CSS:
+
+```css
+.view {
+ background-color: @view_bg_color;
+ color: @view_fg_color;
+}
+```
+
+## Frame
+
+The `.frame` style class can be used with any widget to give it the default
+border.
+
+It's equivalent to using the following CSS:
+
+```css
+.frame {
+ border: 1px solid @borders;
+}
+```
+
+## Flat Header Bar
+
+The `.flat` style class can be used with a [class@Gtk.HeaderBar]` to give it a
+flat appearance.
+
+## Compact Status Page
+
+The `.compact` style class can be used with a [class@Adw.StatusPage] to make it
+take less space. This is usually used with sidebars or popovers.
+
+## Menu Popovers
+
+The `.menu` style class can be used with a [class@Gtk.Popover] to give it a
+menu-like appearance if it has a [class@Gtk.ListBox] or a [class@Gtk.ListView]
+inside it.
+
+## Development Window
+
+The `.devel` style class can be used with [class@Gtk.Window]. This will give
+any [class@Gtk.HeaderBar] inside that window a striped appearance.
+
+This style class is typically used to indicate unstable or nightly applications.
+
+## Inline Tab Bars & Search Bars
+
+By default [class@Gtk.SearchBar] and [class@Adw.TabBar] look like a part of a
+[class@Gtk.HeaderBar] and are intended to be used directly attached to one. With
+the `.inline` style class they have neutral backgrounds and can be used in
+different contexts instead.
+
+# Deprecated Style Classes
+
+The following style classes are deprecated and remain there for compatibility.
+They shouldn't be used in new code.
+
+## `.content`
+
+The `.content` style class can be applied to a [class@Gtk.ListBox] to give it a
+boxed list appearance. The [`.boxed-list`](#boxed-lists-cards) style class is
+completely equivalent to it and should be used instead.
+
+## `.sidebar`
+
+The `.sidebar` style class adds a border at the end of the widget (`border-right`
+for left-to-right text direction, `border-left` for right-to-left) and removes
+background from any [class@Gtk.ListBox] or [class@Gtk.ListView] inside it.
+
+It can be replaced by using the [`.navigation-sidebar`](#sidebars) style class
+on the list widget, combined with a [class@Gtk.Separator] to achieve the border.
+
+## `.app-notification`
+
+The `.app-notification` style class is used with widgets like [class Gtk Box].
+It adds [`.osd](#osd) appearance to the widget and makes its bottom corners
+round. When used together with a [class@Gtk.Overlay] and a [class@Gtk.Revealer],
+it allows to create in-app notifications.
+
+[class@Adw.ToastOverlay] can be used to replace it.
diff --git a/doc/tools/gen-palette.py b/doc/tools/gen-palette.py
new file mode 100755
index 00000000..052d1121
--- /dev/null
+++ b/doc/tools/gen-palette.py
@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+import re
+
+SCSS = '../../src/stylesheet/_palette.scss'
+LIGHT = set(['light_1', 'light_2'])
+DARK = set(['dark_4', 'dark_5'])
+
+colors = []
+regex = re.compile('^\$(\w+)_([1-5]):\s*(#\w+);$')
+
+# Parse colors
+with open(SCSS, 'r') as scss:
+ for line in scss:
+ match = regex.match(line)
+ if match == None:
+ continue
+ name = match.group(1)
+ level = match.group(2)
+ value = match.group(3)
+
+ colors.append((name, level, value))
+
+# Generate table
+print('<table>')
+print(' <tr>')
+print(' <th></th>')
+print(' <th>Name</th>')
+print(' <th>Value</th>')
+print(' </tr>')
+
+for name, level, color in colors:
+ variable = '{}_{}'.format(name, level)
+
+ classes = ''
+ if variable in LIGHT:
+ classes += ' light'
+ if variable in DARK:
+ classes += ' dark'
+
+ print(' <tr>')
+ print(' <td><div class="color-pill{}" style="background-color: {}"/></td>'.format(classes, color))
+ print(' <td><tt>@{}</tt></td>'.format(variable)) # @ is @
+ print(' <td><tt>{}</tt></td>'.format(color))
+ print(' </tr>')
+
+print('</table>')
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
