From 6ad521d1ca49597709941a871a834958df17e41a Mon Sep 17 00:00:00 2001 From: Darren Burns Date: Thu, 24 Oct 2024 17:22:54 +0100 Subject: [PATCH] Further docs updates to get rid of App.dark --- docs/blog/posts/release0-38-0.md | 2 +- docs/guide/command_palette.md | 4 +- docs/tutorial.md | 2 +- reference/_color_system.md | 73 --------------------------- src/textual/app.py | 13 ++++- src/textual/widgets/_toggle_button.py | 4 +- 6 files changed, 17 insertions(+), 81 deletions(-) delete mode 100644 reference/_color_system.md diff --git a/docs/blog/posts/release0-38-0.md b/docs/blog/posts/release0-38-0.md index f08756b13e..01dd85f3ec 100644 --- a/docs/blog/posts/release0-38-0.md +++ b/docs/blog/posts/release0-38-0.md @@ -58,7 +58,7 @@ If you do want to style something outside of the widget you can set `SCOPED_CSS= ## Light and Dark pseudo selectors We've also made a slight quality of life improvement to the CSS, by adding `:light` and `:dark` pseudo selectors. -This allows you to change styles depending on whether you have dark mode enabled or not. +This allows you to change styles depending on whether the app is currently using a light or dark theme. This was possible before, just a little verbose. Here's how you would do it in 0.37.0: diff --git a/docs/guide/command_palette.md b/docs/guide/command_palette.md index 85b30c483b..2c2db2ed35 100644 --- a/docs/guide/command_palette.md +++ b/docs/guide/command_palette.md @@ -11,8 +11,8 @@ Textual will suggest commands as you type in that input. Press ++up++ or ++down++ to select a command from the list, and ++enter++ to invoke it. Commands are looked up via a *fuzzy* search, which means Textual will show commands that match the keys you type in the same order, but not necessarily at the start of the command. -For instance the "Toggle light/dark mode" command will be shown if you type "to" (for **to**ggle), but you could also type "dm" (to match **d**ark **m**ode). -This scheme allows the user to quickly get to a particular command with a minimum of key-presses. +For instance the "Change theme" command will be shown if you type "ch" (for **ch**ange), but you could also type "th" (to match **t**heme). +This scheme allows the user to quickly get to a particular command with fewer key-presses. === "Command Palette" diff --git a/docs/tutorial.md b/docs/tutorial.md index 57c369d448..b79baa494a 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -117,7 +117,7 @@ If you run this code, you should see something like the following: ```{.textual path="docs/examples/tutorial/stopwatch01.py" title="stopwatch01.py"} ``` -Hit the ++d++ key to toggle between light and dark mode. +Hit the ++d++ key to toggle between light and dark themes. ```{.textual path="docs/examples/tutorial/stopwatch01.py" press="d" title="stopwatch01.py"} ``` diff --git a/reference/_color_system.md b/reference/_color_system.md deleted file mode 100644 index 7915c39f95..0000000000 --- a/reference/_color_system.md +++ /dev/null @@ -1,73 +0,0 @@ -_Note: This is kind of a living document, which might not form part of the user-facing documentation._ - -# Textual Color System - -Textual's color system is a palette of colors for building TUIs, and a set of guidelines for how they should be used. Based loosely on Google's Material color system, the Textual color system ensures that elements in the TUI look aesthetically pleasing while maximizing legibility - -## The colors - -There are 10 base colors specified in the Textual Color System. Although it is unlikely that all will need to be specified, since some may be derived from others, and some defaults may not need to be changed. - -A dark mode is automatically derived from the base colors. See Dark Mode below. - -### Shades - -Each color has 6 additional shades (3 darker and 3 lighter), giving a total of 7 shades per color. These are calculated automatically from the base colors. - -### Primary and Secondary - -The _primary_ and _secondary_ colors are used as a background for large areas of the interface, such as headers and sidebars. The secondary color is optional, and if not supplied will be set to be the same as primary. If supplied, the secondary color should be compliment the primary, and together can be considered the _branding colors_ as they have the greatest influence over the look of the TUI. - -### Background and Surface - -The _surface_ colors is the base color which goes behind text. The _background_ color is typically the negative space where there is no content. - -These two colors tend to be very similar, with just enough difference in lightness to tell them apart. They should be chosen for good contrast with the text. - -In light mode the default background is #efefef (a bright grey) and the surface is #f5f5f5 (off white). In dark mode the default background is 100% black, and the default surface is #121212 (very dark grey). - -Note that, although both background and surface support the full range of shades, it may not be possible to darken or lighten them further. i.e. you can't get any lighter than 100% white or darken than 100% black. - -### Panel - -The _panel_ color is typically used as a background to emphasize text on the default surface, or as a UI element that is above the regular UI, such as a menu. - -The default panel color is derived from the surface color by blending it towards either white or black text (depending on mode). - -Unlike background and surface, the panel color is automatically selected so that it can always be lightened or darkened by the full range. - -### Accent - -The _accent_ color should be a contrasting color use in UI elements that should stand out, such as selections, status bars, and underlines. - -### Warning, Error, and Success - -The _warning_, _error_, and _success_ colors have semantic meaning. While they could be any color, by convention warning should be amber / orange, error should be red, and success should be green. - -### System - -The system color is used for system controls such as scrollbars. The default is for the system color to be the same as accent, but it is recommended that a different color is chosen to differentiate app controls from those rendered by the Textual system. - -## Text - -For every color and shade there is an automatically calculated text color, which is either white or black, chosen to produce the greatest contrast. - -The default text color as a slight alpha component, so that it not pure black or pure white, but a slight tint of the background showing through. Additionally, there are two text shades with increasingly greater alpha for reduced intensity text. - -## Dark Mode - -A dark mode is automatically generated from the theme. The dark variations of the primary and secondary colors are generated by blending with the background color. This ensures that the branding remains intact, while still providing dark backgrounds. - -The dark variations of the background and surface color defaults are selected. The other colors remain the same as light mode. The overall effect is that the majority of the interface is dark, with small portions highlighted by color. - -## Naming - -The color system produces a number of constants which are exposed in the CSS via variables. - -The name of the color will return one of the standard set of colors, for example `primary` or `panel`. - -For one of the shade variations, you can append `-darken-1`, `-darken-2`, `-darken-3` for increasingly darker colors, and `-lighten-1`, `lighten-2`, `lighten-3` for increasingly light colors. - -For the contrasting text color, prefix the name with `text-`, for instance `text-primary` or `text-panel`. Note that if the text is to be on top of a darkened or lightened color, it must also be included in the name. i.e. if the background is `primary-darken-2`, then the corresponding text color should be `text-primary-darken-2`. - -The additional two levels of faded text may be requested by appending `-fade-1` or `-fade-2` for decreasing levels of text alpha. diff --git a/src/textual/app.py b/src/textual/app.py index 20f4aa6ed9..84b5fa03bb 100644 --- a/src/textual/app.py +++ b/src/textual/app.py @@ -519,10 +519,10 @@ class MyApp(App[None]): """The name of the currently active theme.""" ansi_theme_dark = Reactive(MONOKAI, init=False) - """Maps ANSI colors to hex colors using a Rich TerminalTheme object while in dark mode.""" + """Maps ANSI colors to hex colors using a Rich TerminalTheme object while using a dark theme.""" ansi_theme_light = Reactive(ALABASTER, init=False) - """Maps ANSI colors to hex colors using a Rich TerminalTheme object while in light mode.""" + """Maps ANSI colors to hex colors using a Rich TerminalTheme object while using a light theme.""" ansi_color = Reactive(False) """Allow ANSI colors in UI?""" @@ -4056,6 +4056,15 @@ async def action_toggle_class(self, selector: str, class_name: str) -> None: """ self.screen.query(selector).toggle_class(class_name) + def action_toggle_dark(self) -> None: + """An [action](/guide/actions) to toggle the theme between textual-light + and textual-dark. This is offered as a convenience to simplify backwards + compatibility with previous versions of Textual which only had light mode + and dark mode.""" + self.theme = ( + "textual-dark" if self.theme == "textual-light" else "textual-light" + ) + def action_focus_next(self) -> None: """An [action](/guide/actions) to focus the next widget.""" self.screen.focus_next() diff --git a/src/textual/widgets/_toggle_button.py b/src/textual/widgets/_toggle_button.py index 02b8999446..68ec3dbb97 100644 --- a/src/textual/widgets/_toggle_button.py +++ b/src/textual/widgets/_toggle_button.py @@ -95,7 +95,7 @@ class ToggleButton(Static, can_focus=True): - /* Base button colors (including in dark mode). */ + /* Base button colors (including in dark themes). */ ToggleButton > .toggle--button { text-style: $block-cursor-text-style; @@ -110,7 +110,7 @@ class ToggleButton(Static, can_focus=True): background: $foreground 25%; } - /* Light mode overrides. */ + /* Light theme overrides. */ ToggleButton:light { color: $text; & > .toggle--button {