From 8bbf831de952b6bd012c1f44c83121ccb3489b4b Mon Sep 17 00:00:00 2001 From: nojhan Date: Sat, 23 Mar 2024 13:24:44 +0100 Subject: [PATCH] doc(design): more on design. - Move design sketches in /docs/ --- docs/README.md | 100 +++++++++++++++--- .../liquidprompt_dotmatrix_design.odt | Bin .../liquidprompt_dotmatrix_design.svg | 0 3 files changed, 87 insertions(+), 13 deletions(-) rename liquidprompt_dotmatrix_design.odt => docs/liquidprompt_dotmatrix_design.odt (100%) rename liquidprompt_dotmatrix_design.svg => docs/liquidprompt_dotmatrix_design.svg (100%) diff --git a/docs/README.md b/docs/README.md index dc85a68..c2ea1e0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,6 @@ # Introduction - - This article is made of two main sections: generic design principles, and Jolly's design principles. @@ -15,8 +13,8 @@ The Jolly's design principles are more or less specific to the Jolly theme. ## What is a Prompt? -There are two kind of computer scientists: those who use the command line, -and those who are retired. Even developers who embrace highly integrated development interfaces have some kind of terminal available in some panel of their IDE. +There are two kind of computer scientists: those who use the command line, and those who are retired. +Even developers who embrace highly integrated development interfaces have some kind of terminal available in some panel of their IDE. Like it or not, the shell is a core part of everyday life for most of the people expecting their computer to work for them. Now the shell actually has access to a lot of information about the computer. @@ -29,7 +27,7 @@ The prompt is this string of characters displayed right in front of the line whe In the most common default configuration, it displays only three pieces of information: the user, the hostname, and the path —`user@hostname:path $ `. -But it can display more! And this is the objective of prompt systems. +But it can display more! And this is the objective of *prompt systems*. Those "prompts" (to be short) actually add a lot of information to this area of the command line. For example, the most common feature is to display the state of the Git repository the user is in. @@ -89,7 +87,7 @@ be obvious to the user, depending on their location on the screen and/or their s Section styling should not overflow on neighbor sections. For instance, given that the terminal is organized as a grid of characters, -the background of two close character will blend. +the background of two close (horizontally or vertically) characters will blend. Therefore, one should maintain a certain degree of contrast between sections that are touching each other but have a different semantics. @@ -125,9 +123,6 @@ always be considered important, as they may drastically alter the workflow of th > while the others are in background-colored sections. -## Seamless - - ## Scoped States that are measured and not directly changed by the user should be hidden by default. @@ -135,6 +130,7 @@ Counters that can fall down to zero should be hidden by default. > In Jolly, *sensors* are hidden by default, while *situation* and *location* > information are always shown, even if set to the default state. +> However, the default states are represented in the smallest possible way, like a single icon. ## Measured @@ -150,23 +146,101 @@ States that rarely change or evolve slowly are less important. ## Configurable -Each aspect of theming should have a related configurable variable. +Each aspect of theming should have a related configuration variable. # Jolly's Design Principles ## Stability -## Proximity +Essential information should ideally be located at the same location on screen, +whatever the displayed states. +New information being shown after a predictable state change should not +change too much the location of information previously displayed. + +> Using four sections allows Jolly to drastically improve the stability of the prompt, +> as opposed to a prompt on a single line. +> The less stable section is the VCS one, which often changes after each command when the user is working on their repository. +> Sections are thus organized from left to right, in decreasing order of stability. +> Jolly always displays important segments, even in their default state, so that they are always located where the user expect them to be. + ## Sectioning -## Accessibility +The prompts having issued the previous commands should be easy to find while the user is scrolling up the terminal. + +> Jolly uses both background-colored sections that are always displayed and a line traversing the whole terminal to separate all command outputs in sections. +> The graphical design of the prompt itself is quite rare in classical commands outputs, making it easy to spot. +> Finding the command that issued the output is as easy as finding the horizontal line. + + +## Proximity + +The more important and/or the more frequently updated information should be displayed the closer to where the user is looking: the prompt cursor. +Related information should be displayed close to each other, especially if there is some semantic meaning linking them. + +If the information is to be displayed far away, a small segment may be used to recall the user that they should look elswhere. + +> In Jolly, the path (one of the —if not *the*— most important information) usually appears on top of the prompt's cursor location. +> Admin privileges is shown on the prompt's mark, right next to the prompt's cursor. +> VCS information is also next to the input area. +> +> The location at the end of the path can display some right-pointing arrows, recalling the user to look at the sensors section, if there are many information displayed there. + + +## Segments + +To implement the *accentuated* principle, Jolly uses background-colored segments of information. +To ease the visual browsing of those segments, it uses the visual separators introduced by the *Powerline* project. + +> While Jolly can theoretically use many of the "powerline" characters as separators, it recommends using the "arrow" one, which fits better the *semantic sequence* principle. -## Semantic Spaces ## Semantic Sequences +Segments are ordered in sequences that have a meaning. +For instance from the more generic to the more specific, from a natural order of action, or from an architecture hierarchy. + +> The first line of Jolly display the classical how-who-where sequence. +> The VCS section displays elements from the more remote to the more local. +> Spaced reverse arrows in the VCS sections actually show the direction of the expected action +> (e.g. "to be pushed" = local-to-remote = right-to-left). + + +## Semantic Spaces + +Jolly makes use of negative spaces between segments to convey information. +This allows for a compact display, and avoid cluttering the screen with icons. + +When displaying something with a space, the direction of the segments are reversed, making them more easy to spot, at no cost. + +It is possible to insert a separator character within a space, to emphasize its importance. + +Spaces are generally used to mean some kind of "disconnected" state. + +> Jolly spaces comes in three levels: simple space (no inserted character), light space (light arrow inserted in the space) and strong space (heavy, colored arrow). +> Jolly uses spaces to indicate the type of network connection (there is no "direct" connection), the fact that the user does not have writing rights (they are "disconnected" from the directory), or the fact that a state has diverged between local and remote. + + +## Semantic Accessibile Colors + +To avoid colorblindness issues, Jolly relies on as few colors as possible, and tries to maximize the contrast between segments. + +The basic display is built of alternating black and white segments, which should be readable on both dark and light terminal backgrounds. + +Important information may be displayed using two other colors: one for information that should be noticed, and one for warnings and errors. + +> Jolly allows the user to select whatever pair of colors fits their colorblindness issues, and comes with several presets. +> Its default is set to blue/yellow, following the most classical recommendation to bypass the most common colorblindness issues. +> The basic segments use tones of dark and light greys with AAA contrast between them, appearing as black and white on many classical terminal backgrounds. + + ## Semantic Thresholds +Qantitative measurements (number of something, sensors, etc.) may be displayed in three states, each of which is associated with a semantic color: +1. below lower threshold: black or white, +2. between lower and higher threshold: *note* color (blue, by default), +3. above higher threshold: *warning* color (yellow, by default). + +> For instance, the number of commits to be pushed, or the number of modified lines in the VCS section are all displayed with this semantics. diff --git a/liquidprompt_dotmatrix_design.odt b/docs/liquidprompt_dotmatrix_design.odt similarity index 100% rename from liquidprompt_dotmatrix_design.odt rename to docs/liquidprompt_dotmatrix_design.odt diff --git a/liquidprompt_dotmatrix_design.svg b/docs/liquidprompt_dotmatrix_design.svg similarity index 100% rename from liquidprompt_dotmatrix_design.svg rename to docs/liquidprompt_dotmatrix_design.svg