From 76c58978b99a1ca9733c240ab3001d3db7f96d78 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 7 Dec 2022 10:36:28 -0600 Subject: [PATCH 1/5] Add article about using light themes --- .../learn/shell/using-light-theme.md | 138 ++++++++++++++++++ reference/docs-conceptual/toc.yml | 2 + 2 files changed, 140 insertions(+) create mode 100644 reference/docs-conceptual/learn/shell/using-light-theme.md diff --git a/reference/docs-conceptual/learn/shell/using-light-theme.md b/reference/docs-conceptual/learn/shell/using-light-theme.md new file mode 100644 index 000000000000..7cf67be55e98 --- /dev/null +++ b/reference/docs-conceptual/learn/shell/using-light-theme.md @@ -0,0 +1,138 @@ +--- +description: > + This article shows how to configure PSReadLine color settings for a light themed terminal. +ms.date: 12/07/2022 +title: Configuring a light colored theme +--- +# Configuring a light colored theme + +The default colors for both PowerShell and **PSReadLine** are selected for dark background terminal. +However, some users may choose to use a light background with dark text. Since most of the default +colors don't set the background, using light foreground colors on a light background produces +unreadable text. + +The **PSReadLine** allows you to define colors for 18 different syntax elements. You can view the +current settings using the `Get-PSReadLineOption` cmdlet. + +```Output +EditMode : Windows +AddToHistoryHandler : System.Func`2[System.String,System.Object] +HistoryNoDuplicates : True +HistorySavePath : C:\Users\user1\AppData\Roaming\Microsoft\Wind... +HistorySaveStyle : SaveIncrementally +HistorySearchCaseSensitive : False +HistorySearchCursorMovesToEnd : False +MaximumHistoryCount : 4096 +ContinuationPrompt : >> +ExtraPromptLineCount : 0 +PromptText : {> } +BellStyle : Audible +DingDuration : 50 +DingTone : 1221 +CommandsToValidateScriptBlockArguments : {ForEach-Object, %, Invoke-Command, icm...} +CommandValidationHandler : +CompletionQueryItems : 100 +MaximumKillRingCount : 10 +ShowToolTips : True +ViModeIndicator : None +WordDelimiters : ;:,.[]{}()/\|^&*-=+'"-—― +AnsiEscapeTimeout : 100 +PredictionSource : HistoryAndPlugin +PredictionViewStyle : InlineView +CommandColor : "`e[93m" +CommentColor : "`e[32m" +ContinuationPromptColor : "`e[37m" +DefaultTokenColor : "`e[37m" +EmphasisColor : "`e[96m" +ErrorColor : "`e[91m" +InlinePredictionColor : "`e[38;5;238m" +KeywordColor : "`e[92m" +ListPredictionColor : "`e[33m" +ListPredictionSelectedColor : "`e[48;5;238m" +MemberColor : "`e[97m" +NumberColor : "`e[97m" +OperatorColor : "`e[90m" +ParameterColor : "`e[90m" +SelectionColor : "`e[30;47m" +StringColor : "`e[36m" +TypeColor : "`e[37m" +VariableColor : "`e[92m" +``` + +The color settings are stored as strings containing ANSI escape sequences that change the color in +your terminal. Using the `Set-PSReadLineOption` cmdlet you can change the colors to values that work +better for a light-colored background. + +## Defining colors for a light theme + +The original PowerShell ISE can be configured to use a light theme for both the editor and console +panes. You can also view and change the colors that the ISE uses for various syntax and output +types. You can use these color choices to define a similar theme for **PSReadLine**. + +The following hashtable defines colors for **PSReadLine** that mimic the colors in the PowerShell +ISE. + +```powershell +$ISETheme = @{ + Command = $PSStyle.Foreground.FromRGB(0x0000FF) + Comment = $PSStyle.Foreground.FromRGB(0x006400) + ContinuationPrompt = $PSStyle.Foreground.FromRGB(0x0000FF) + Default = $PSStyle.Foreground.FromRGB(0x0000FF) + Emphasis = $PSStyle.Foreground.FromRGB(0x287BF0) + Error = $PSStyle.Foreground.FromRGB(0xE50000) + InlinePrediction = $PSStyle.Foreground.FromRGB(0x93A1A1) + Keyword = $PSStyle.Foreground.FromRGB(0x00008b) + ListPrediction = $PSStyle.Foreground.FromRGB(0x06DE00) + Member = $PSStyle.Foreground.FromRGB(0x000000) + Number = $PSStyle.Foreground.FromRGB(0x800080) + Operator = $PSStyle.Foreground.FromRGB(0x757575) + Parameter = $PSStyle.Foreground.FromRGB(0x000080) + String = $PSStyle.Foreground.FromRGB(0x8b0000) + Type = $PSStyle.Foreground.FromRGB(0x008080) + Variable = $PSStyle.Foreground.FromRGB(0xff4500) + ListPredictionSelected = $PSStyle.Background.FromRGB(0x93A1A1) + Selection = $PSStyle.Background.FromRGB(0x00BFFF) +} +``` + +In PowerShell 7.2 and higher you can use the `FromRGB()` method of `$PSStyle` to create the ANSI +escape sequences for the colors you want. + +For more information about `PSStyle`, see [about_ANSI_Terminals][01]. + +For more information about ANSI escape sequences, see the [ANSI escape code][04] article in +Wikipedia. + +## Setting the color theme in your profile + +To have the color settings you want in every PowerShell session, you must add the configuration +settings to your PowerShell profile script. For an example, see +[Customizing your shell environment][02] + +Add the `$ISETheme` variable and the following `Set-PSReadLineOption` command to your profile. + +```powershell +Set-PSReadLineOption -Colors $ISETheme +``` + +## Choosing colors for accessibility + +The ISE color theme may not work for users with color-blindness or other conditions that limit their +ability to see colors. + +The [World Wide Web Consortium (W3C)][05] has recommendations for using colors for accessibility. +The Web Content Accessibility Guidelines (WCAG) 2.1 recommends that "visual presentation of text and +images of text has a contrast ratio of at least 4.5:1." For more information, see +[Success Criterion 1.4.3 Contrast (Minimum)][06]. + +The [Contrast Ratio][03] website provides a tool that lets you pick foreground and background +colors and measure the contrast. You can use this tool to find color combinations that work best for +you. + + +[01]: /powershell/module/Microsoft.PowerShell.Core/About/about_ANSI_Terminals +[02]: creating-profile.md +[03]: https://contrast-ratio.com/ +[04]: https://en.wikipedia.org/wiki/ANSI_escape_code +[05]: https://www.w3.org/ +[06]: https://www.w3.org/TR/WCAG/#contrast-minimum diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index f6884735f29c..fdfa52cf7af8 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -86,6 +86,8 @@ items: href: learn/shell/using-aliases.md - name: Customizing your shell environment href: learn/shell/creating-profiles.md + - name: Configuring a light colored theme + href: learn/shell/using-light-theme.md - name: Deep dives items: - name: Overview From c9e099c5a6f849b52c2eb2ff6a1fb1527066063a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 7 Dec 2022 10:40:49 -0600 Subject: [PATCH 2/5] Fix broken link --- reference/docs-conceptual/learn/shell/using-light-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/docs-conceptual/learn/shell/using-light-theme.md b/reference/docs-conceptual/learn/shell/using-light-theme.md index 7cf67be55e98..3d1f8b814222 100644 --- a/reference/docs-conceptual/learn/shell/using-light-theme.md +++ b/reference/docs-conceptual/learn/shell/using-light-theme.md @@ -131,7 +131,7 @@ you. [01]: /powershell/module/Microsoft.PowerShell.Core/About/about_ANSI_Terminals -[02]: creating-profile.md +[02]: creating-profiles.md [03]: https://contrast-ratio.com/ [04]: https://en.wikipedia.org/wiki/ANSI_escape_code [05]: https://www.w3.org/ From 3ad7ebe87fd3d469965e11564e0a4bed9d398c49 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 7 Dec 2022 10:43:27 -0600 Subject: [PATCH 3/5] fix typos --- .../docs-conceptual/learn/shell/using-light-theme.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/docs-conceptual/learn/shell/using-light-theme.md b/reference/docs-conceptual/learn/shell/using-light-theme.md index 3d1f8b814222..7a84188333c4 100644 --- a/reference/docs-conceptual/learn/shell/using-light-theme.md +++ b/reference/docs-conceptual/learn/shell/using-light-theme.md @@ -6,12 +6,12 @@ title: Configuring a light colored theme --- # Configuring a light colored theme -The default colors for both PowerShell and **PSReadLine** are selected for dark background terminal. -However, some users may choose to use a light background with dark text. Since most of the default -colors don't set the background, using light foreground colors on a light background produces -unreadable text. +The default colors for both PowerShell and **PSReadLine** are selected for a dark background +terminal. However, some users may choose to use a light background with dark text. Since most of the +default colors don't set the background, using light foreground colors on a light background +produces unreadable text. -The **PSReadLine** allows you to define colors for 18 different syntax elements. You can view the +**PSReadLine** allows you to define colors for 18 different syntax elements. You can view the current settings using the `Get-PSReadLineOption` cmdlet. ```Output From 4d2f327082336f88e3fdbe1cec380ce5ee9e5fce Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 7 Dec 2022 12:23:33 -0600 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Mikey Lombardi (He/Him) --- reference/docs-conceptual/learn/shell/using-light-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/docs-conceptual/learn/shell/using-light-theme.md b/reference/docs-conceptual/learn/shell/using-light-theme.md index 7a84188333c4..365548912e10 100644 --- a/reference/docs-conceptual/learn/shell/using-light-theme.md +++ b/reference/docs-conceptual/learn/shell/using-light-theme.md @@ -65,7 +65,7 @@ better for a light-colored background. ## Defining colors for a light theme -The original PowerShell ISE can be configured to use a light theme for both the editor and console +The PowerShell ISE can be configured to use a light theme for both the editor and console panes. You can also view and change the colors that the ISE uses for various syntax and output types. You can use these color choices to define a similar theme for **PSReadLine**. From bde7e1f2d0053bfa48900a63e0d2af4070be22d0 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 7 Dec 2022 12:30:28 -0600 Subject: [PATCH 5/5] Editorial changes --- .../learn/shell/using-light-theme.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/reference/docs-conceptual/learn/shell/using-light-theme.md b/reference/docs-conceptual/learn/shell/using-light-theme.md index 365548912e10..d92ab5290b3f 100644 --- a/reference/docs-conceptual/learn/shell/using-light-theme.md +++ b/reference/docs-conceptual/learn/shell/using-light-theme.md @@ -65,9 +65,9 @@ better for a light-colored background. ## Defining colors for a light theme -The PowerShell ISE can be configured to use a light theme for both the editor and console -panes. You can also view and change the colors that the ISE uses for various syntax and output -types. You can use these color choices to define a similar theme for **PSReadLine**. +The PowerShell ISE can be configured to use a light theme for both the editor and console panes. You +can also view and change the colors that the ISE uses for various syntax and output types. You can +use these color choices to define a similar theme for **PSReadLine**. The following hashtable defines colors for **PSReadLine** that mimic the colors in the PowerShell ISE. @@ -95,13 +95,14 @@ $ISETheme = @{ } ``` -In PowerShell 7.2 and higher you can use the `FromRGB()` method of `$PSStyle` to create the ANSI -escape sequences for the colors you want. - -For more information about `PSStyle`, see [about_ANSI_Terminals][01]. - -For more information about ANSI escape sequences, see the [ANSI escape code][04] article in -Wikipedia. +> [!NOTE] +> In PowerShell 7.2 and higher you can use the `FromRGB()` method of `$PSStyle` to create the ANSI +> escape sequences for the colors you want. +> +> For more information about `PSStyle`, see [about_ANSI_Terminals][01]. +> +> For more information about ANSI escape sequences, see the [ANSI escape code][04] article in +> Wikipedia. ## Setting the color theme in your profile