UI style errors: Menu items capitalization and … (ellipses) mark misuse

[PhMajerus]

Windows Terminal version

1.20.10572.0

Windows build number

10.0.22631.3235

Other Software

No response

Steps to reproduce

Display the tab contextual menu, preferably with a second pane open to show all options.

There are several problems with this menu.

First: Excessive capitalization

If you check out the style guide: https://learn.microsoft.com/en-us/style-guide/text-formatting/formatting-common-text-elements
You'll see that UI text or strings should use Sentence-style capitalization, this is further described at https://learn.microsoft.com/en-us/style-guide/capitalization

capitalize the first word and lowercase the rest.
Exceptions: Proper nouns, including brand, product, and service names, are always capitalized.
If a title or heading includes a colon, capitalize the first word after it.

Tab, New, Window, Right are not brands, products, or service names, they should not be capitalized.
This looks worse in other languages as determiners make the capitalized words lose their vertical alignment, as seen in #16819.

Second: Misuse of … (ellipses)

From the Windows UX design guide: https://learn.microsoft.com/en-us/windows/win32/uxguide/text-ui#guidelines

Ellipses mean incompleteness. Use ellipses in UI text as follows:

Commands: Indicate that a command needs additional information.
Don't use an ellipsis whenever an action displays another window only when additional information is required.
For more information, see [Command Buttons](https://learn.microsoft.com/en-us/windows/win32/uxguide/ctrl-command-buttons).

(… more details about truncated text, use in data and labels not included here)

I know this is getting out of style, but … and > next to menu items were originally designed to provide predictability.
The … after a menu item means selecting it will display a follow-up dialog or window asking for more options before completing the selected action, while > after a menu item means selecting it will display a cascading submenu, finally, neither means selecting it will perform the action immediately.
Therefore, they are mutually exclusive, you cannot have … and > on the same menu item, clicking it either displays a dialog/window, or a submenu, it cannot do both.

More modern Windows UI is trying to get rid of … on menu items, trading discoverability and predictability for the sake of visual style, but including it when it doesn't mean a subsequent window will get displayed breaks both the UI guidelines we had since Windows 3.x, and the modern look. Those Close… have to go.

Note the tab contextual menu was taken as an example because it contains all the problems I wanted to mention, but other menus also contain similar errors.

Expected Behavior

UI consistency (didn't there used to be a UI guidelines check before inclusion as a Windows component?).

Actual Behavior

Unpredictability and confusion 🤪

[DHowett]

We would be more than happy to accept a PR that fixes these things! I'll mark it up.

[PhMajerus]

I would also change Color… to Change tab color…, making it more clear and justifying the …, since it clarifies it is the color of the tab that will be changed, but only after a subsequent dialog that requests more information about the color and can still be cancelled.

To old-timers like me, the … always mean "it's safe to click to find out more about what this menu item does because there's another step where it can still be cancelled".

[HartJesse]

I'm still a fresh beginner I saw this as a "good first issue" and thought I would try to take a look at the repository but I can't even navigate the repository successfully to find the relevant files for the issue let alone solve it. If anyone sees this and would like to assist me that would be very much appreciated I want to learn how this program works and more!

[leejy12]

@HartJesse Resource files for different languages are in src/cascadia/TerminalApp/Resources.

However, I think to fully resolve this issue, all locales must be updated, not just English.

[DHowett]

However, I think to fully resolve this issue, all locales must be updated, not just English.

It will be sufficient to update only the English text. The rest of the localizations are automatically uploaded to a human translation service.

[HartJesse]

Thanks for the info you all, I just started learning about resource files and how they work as a result of all this. I will continue working on the issues.

[HartJesse]

I believe I have made the appropriate changes in the associated resource file however I am unable to build and test the repository. I have been trying everything but I keep getting errors stating I need to reconfigure my mappings, solutions need to be built and deployed first etc. If anyone can point me in the next correct direction that would be amazing!

[lhecker]

It's hard to say what your issue is given just your description. I believe it would make things easier if you post screenshots or copy the error message here. Given that you mentioned "mappings" I suspect that you forgot to update your git submodules however. If you open cmd/powershell in the repository you can do this with the following command:

git submodule update --init

[HartJesse]

@lhecker Oh yeah I definitely did not do that I will try to do that next thank you! Here is a screenshot of my visual studio right now.

[DHowett]

Oh! You can ignore that error. VS hates our project and refuses to specify why, but it works fine.

If you select Debug and x64 from those Configuration and Platform dropdowns, CascadiaPackage from the Target dropdown, and click the Play/Run button it should work!

[HarshNarayanJha]

@DHowett, PR #16886 is live!

[PhMajerus]

@HarshNarayanJha Thanks for taking on this issue.
I had a quick look at the PR.

The TabCloseSubMenu is still "Close...". If I'm not mistaken, that is the menu item that shows the submenu on my screenshot starting this thread. It should be "Close" without the ellipses as it will have the ">".

The NewTabSplitButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name is "New Tab". I'm not sure where this label is used, but it probably should be "New tab".
The AboutDialog.PrimaryButtonText should probably be "Send feedback", it's not referring to the Feeback hub, and Notepad uses the lowercase version as well for the same purpose.
The ExportTabText should probably use lowercase as well: "Export text". Same for PlainText: "Plain text".

You changed "Admin" to "admin", but left an uppercase for RunAsAdminFlyout.Text: "Run as Administrator". This one is less clear cut because there is an "Administrator" default user account, but the same label in the shell uses "Run as administrator". I think it should be lowercase.
I would suggest we also take the opportunity to change "This Terminal window is running as admin" to "This Terminal window is running as administrator". What do you think @DHowett ?
I know most power users simply say "admin", but every other piece of system UI I checked uses the full "administrator" term, such as "Run as administrator" in the shell and in Terminal itself, "Administrators" group in Local Users and Groups,….
I think keeping the full term will make it more consistent and easier to understand for all the non-native English using the en-us UI as a global default. (I love all the localization work Microsoft has done over the years, but some global companies are not used to the idea of just having MUI and letting each user in subsidiaries pick their preferred UI language just yet).

Another arbitration question to Dustin about LargePasteDialog.Content, "You are about to paste text that is longer than 5 KiB. Do you wish to continue?". It is correct, but Windows has always used "KB" for binary units, so wouldn't it be better to be consistent with the shell and avoid the "KiB"?

[DHowett]

Another arbitration question to Dustin about LargePasteDialog.Content, "You are about to paste text that is longer than 5 KiB. Do you wish to continue?". It is correct, but Windows has always used "KB" for binary units, so wouldn't it be better to be consistent with the shell and avoid the "KiB"?

This is my one hill to die on! If ever I could change the style guide itself, I would. KiB stays, or we change the value to exactly 5000 😉

[PhMajerus]

@DHowett You know you could actually write a COM shell extension that adds a column showing file sizes with the KiB, MiB, … labels in the File Explorer if you want 😉 You could even add another one that uses 1000 instead of 1024 multipliers with the traditional KB, MB, … labels. After all, using 1024 to be able to compute it using a shift operation isn't exactly faster than a proper /1000 anymore. You could start a trend away from 1024 and avoid future generations the confusion rooted in 1970's performance hacks.
I only wish Explorer would be consistent with itself to display files sizes… It has been Ceiling sizes in the Size column and Flooring them in the status bar for as long as I can remember. Once you notice it, it will bother you several times a day… Which is why I now told you, so you can pester guys from the Explorer team to fix it when you run across them 😁.

But about Terminal, now that you mention it, the problem isn't only to make it clear it's 5120 and not 5000. Ok, KiB makes it clear it's 5120 bytes, but that doesn't tell me how much text that is.
I mean I understand it's stored as bytes and that's why you use binary multipliers and bytes, and you probably mean 5120 UTF-8 code units, but to me 5KiB of text on NT means 2560 UTF-16 code units, and someone else who doesn't know about UTF might assume you mean 5120 code points because they don't know a code point doesn't always take a single byte, or 5120 grapheme clusters. So "5KiB of text" is unclear anyway, even with your KiB.

I would use "You are about to paste text that is longer than 5120 UTF-8 code units. Do you wish to continue?" to remove all ambiguity. It's clearer and isn't wrong per the style guide and inconsistent with everything else on Windows.
You could round it down to 5000 if you want, but keeping the same wording to avoid UTF-* misunderstandings. What do you think?

[HarshNarayanJha]

@HarshNarayanJha Thanks for taking on this issue.
I had a quick look at the PR.

The TabCloseSubMenu is still "Close...". If I'm not mistaken, that is the menu item that shows the submenu on my screenshot starting this thread. It should be "Close" without the ellipses as it will have the ">".

The NewTabSplitButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name is "New Tab". I'm not sure where this label is used, but it probably should be "New tab".
The AboutDialog.PrimaryButtonText should probably be "Send feedback", it's not referring to the Feeback hub, and Notepad uses the lowercase version as well for the same purpose.
The ExportTabText should probably use lowercase as well: "Export text". Same for PlainText: "Plain text".

You changed "Admin" to "admin", but left an uppercase for RunAsAdminFlyout.Text: "Run as Administrator". This one is less clear cut because there is an "Administrator" default user account, but the same label in the shell uses "Run as administrator". I think it should be lowercase.
I would suggest we also take the opportunity to change "This Terminal window is running as admin" to "This Terminal window is running as administrator". What do you think @DHowett ?
I know most power users simply say "admin", but every other piece of system UI I checked uses the full "administrator" term, such as "Run as administrator" in the shell and in Terminal itself, "Administrators" group in Local Users and Groups,….
I think keeping the full term will make it more consistent and easier to understand for all the non-native English using the en-us UI as a global default. (I love all the localization work Microsoft has done over the years, but some global companies are not used to the idea of just having MUI and letting each user in subsidiaries pick their preferred UI language just yet).

Another arbitration question to Dustin about LargePasteDialog.Content, "You are about to paste text that is longer than 5 KiB. Do you wish to continue?". It is correct, but Windows has always used "KB" for binary units, so wouldn't it be better to be consistent with the shell and avoid the "KiB"?

Guess I missed those strings! I will push a commit soon

[HartJesse]

@HarshNarayanJha I have also been looking into fixing this issue I corrected most of the strings in my own branch of the repository but was never able to build my repository and run the new version if the terminal on my PC. You appear to be getting it to run on your machine would you ever be willing to hop on discord or something to show me what I'm doing wrong because I would like to learn more and be able to solve some issues officially myself! Anyone else who may be reading this is also open to help :)

[tusharsnx]

You appear to be getting it to run on your machine would you ever be willing to hop on discord

I can help. You can reach out to me at (tusharsnx) on discord 🙂

Just a side note, I'd love a discord server for WT development queries and general discussion. People would be able to collaborate with others for fixes and features. (Yeah, I know Github Discussion exists but I rather use Discord 😄)

"You are about to paste text that is longer than 5120 UTF-8 code units. Do you wish to continue?"

"... UTF-8 code units" sounds very technical IMO.

[HartJesse]

@tusharsnx I will contact you in the morning on discord then thanks for offering your assistance:)

[HarshNarayanJha]

@HarshNarayanJha I have also been looking into fixing this issue I corrected most of the strings in my own branch of the repository but was never able to build my repository and run the new version if the terminal on my PC. You appear to be getting it to run on your machine would you ever be willing to hop on discord or something to show me what I'm doing wrong because I would like to learn more and be able to solve some issues officially myself! Anyone else who may be reading this is also open to help :)

Sure @HartJesse I would love to collab. May I know your discord?

[HarshNarayanJha]

Should I keep the ellipses in New Tab... and Split Pane... ???

[PhMajerus]

I couldn't find New tab with ellipses.
I think the one below just needs to be changed to lowercase. I don't think it appears in the UI by itself, probably for screen readers and automation as a label for the +|v button.

  <data name="NewTabSplitButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name" xml:space="preserve">
    <value>New Tab</value>
  </data>

For Split pane, if you're talking about this:

  <data name="SplitPaneText" xml:space="preserve">
    <value>Split pane</value>
  </data>

I'm not sure where this appears in the UI. The rule is to have ellipses only if the action mentionned in the menu item label does not get executed before further details are provided in a subsequent dialog or UI element.
For example, Find should theoretically have ... because it doesn't find anything when selected, instead it shows a UI to select what to find:

  <data name="FindText" xml:space="preserve">
    <value>Find</value>
    <value>Find...</value>
  </data>

Of course, even the new Notepad doesn't follow the rules properly, but the original Notepad since Windows 3.0 to Windows 10 did use Find... in their Edit menu.
Same goes for Export text..., as there is a subsequent save dialog before the export text action is executed.
This is the reason traditional apps had Save but Save as..., because save would immediately overwrite the existing file, while save as would request the file name before saving anything.

I'm not sure if they're supposed to update the style guide to remove all ellipses, but everything I could find still explains the same rules we had since Windows 3.0.
Note I understand if @DHowett prefers to keep all those without ellipses. There is a mix of style in Windows built-in apps at this time and I'm not sure where they're going. The only thing that definitely cannot happen is the Close... > for TabCloseSubMenu, cascading menus never have ....

[HarshNarayanJha]

I couldn't find New tab with ellipses. I think the one below just needs to be changed to lowercase. I don't think it appears in the UI by itself, probably for screen readers and automation as a label for the +|v button.

  <data name="NewTabSplitButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name" xml:space="preserve">
    <value>New Tab</value>
  </data>

For Split pane, if you're talking about this:

  <data name="SplitPaneText" xml:space="preserve">
    <value>Split pane</value>
  </data>

I'm not sure where this appears in the UI. The rule is to have ellipses only if the action mentionned in the menu item label does not get executed before further details are provided in a subsequent dialog or UI element.

I was talking about these (TerminalSettingsModel)

I couldn't find New tab with ellipses. I think the one below just needs to be changed to lowercase. I don't think it appears in the UI by itself, probably for screen readers and automation as a label for the +|v button.

  <data name="NewTabSplitButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name" xml:space="preserve">
    <value>New Tab</value>
  </data>

For Split pane, if you're talking about this:

  <data name="SplitPaneText" xml:space="preserve">
    <value>Split pane</value>
  </data>

I'm not sure where this appears in the UI. The rule is to have ellipses only if the action mentionned in the menu item label does not get executed before further details are provided in a subsequent dialog or UI element. For example, Find should theoretically have ... because it doesn't find anything when selected, instead it shows a UI to select what to find:

  <data name="FindText" xml:space="preserve">
    <value>Find</value>
    <value>Find...</value>
  </data>

Of course, even the new Notepad doesn't follow the rules properly, but the original Notepad since Windows 3.0 to Windows 10 did use Find... in their Edit menu. Same goes for Export text..., as there is a subsequent save dialog before the export text action is executed. This is the reason traditional apps had Save but Save as..., because save would immediately overwrite the existing file, while save as would request the file name before saving anything.

I'm not sure if they're supposed to update the style guide to remove all ellipses, but everything I could find still explains the same rules we had since Windows 3.0. Note I understand if @DHowett prefers to keep all those without ellipses. There is a mix of style in Windows built-in apps at this time and I'm not sure where they're going. The only thing that definitely cannot happen is the Close... > for TabCloseSubMenu, cascading menus never have ....

Yup I agree. I have no idea if I should add (...) to Find and Export options, as they do open a new window to continue the task, denoting that there is at least one stage before which it can be dismissed

[PhMajerus]

Looking at recent versions of Word and Excel, and the new versions of Notepad and Paint, it seems they removed the ... from all menu items.
In Terminal, only Change tab color... remains.
To me it doesn't make sense to have Change tab color..., but Export text and Find without ... in the same menu. I would suggest getting rid of the last remaining one to achieve consistency with other modern built-in apps.

[HarshNarayanJha]

Though I guess resource files have something else to say:

[PhMajerus]

Yeah, because they are trying to get rid of ... in menu items to make them look better, but they are keeping them on buttons, and that's a button label.
Don't look at me to justify that, I'm advocating for keeping them in menus as well and keep predictability above looks, and I'm not a Microsoft employee. I believe Dustin has the final say on which style Terminal should use.

Old style conventions would also use >> on a button that extends the current dialog, such as for TabColorCustomButton.Content.
You know, like the system (GDI) color picker dialog did for decades:

Style guidelines are a mess globally at Microsoft right now, so I don't want to pester Dustin too much with these. Especially since I'm hoping he will approve some of my own PRs in Cascadia-Code 😉.

[HarshNarayanJha]

Yeah, because they are trying to get rid of ... in menu items to make them look better, but they are keeping them on buttons, and that's a button label. Don't look at me to justify that, I'm advocating for keeping them in menus as well and keep predictability above looks, and I'm not a Microsoft employee. I believe Dustin has the final say on which style Terminal should use.

I will like the idea that .. is used and only used for actions (both menus and button) which open new windows/dialogs. It feels more consistent.

Old style conventions would also use >> on a button that extends the current dialog, such as for TabColorCustomButton.Content. You know, like the system color picker dialog did for decades:

Style guidelines are a mess globally at Microsoft right now, so I don't want to pester Dustin too much with these. Especially since I'm hoping he will approve some of my own PRs in Cascadia-Code 😉.

Yes you are right. Keeping track of these small strings in such a large project is a real challenge. I really don't know why Paint still uses >> 😂 . Guess this is a side effect of some apps still using Windows 7 UI.

[zadjii-msft]

Okay so most everything else in this thread I think I'm on board with. But the last Split pane... and New tab..., I'm not so sure how I feel. Those are used for the Command Palette, for nested commands:

(some of those are my own commands, but most of those are built-in)

Those entries have the ... to indicate that there will be additional command palette entries listed under it. But those do have >'s on them, but I dunno. Both feels right to me?

[PhMajerus]

@zadjii-msft
The command palette isn't exactly a cascading menu, so I have less strong feelings about that one.
But New Tab should definitely have a lowercase. As for the ...combined with >, when I filter for "new tab", the ... seem to stand out and are out of place with the following >:

Similar for Split Pane, it's the only one with Pane using an uppercase, and the ... seem out of place as well.

Looking at all the items with "...", I believe these are the only built-in ones:

Open settings shouldn't have the ... because while it shows a new page, showing that settings page is the action of that item, it doesn't request further options before executing the open settings action.
For Rename tab title, I think either is ok, because it renames in place in the UI, so it can be interpreted as either asking for more details or for starting the advertised action immediately. However, the File Explorer doesn't use ... after the menu item that starts renaming a file or folder in-place. I do feel weird we're renaming to change the title, not the name though, I feel like either Rename tab or Change tab title would fit better, and the tab contextual menu uses Rename tab for what seems to start the same action, but that may be because I'm not a native speaker.
Rename window... seems to have the ... justified because it opens a popup prompt for the new name.
For Select color scheme... >, I feel like the ... are wrong because of the >, and I think Change color scheme > would be clearer as the action is to change the currently active color scheme, not select it to do something with it like you would Select all text to then copy it for example.
Same for Set background opacity... >, I would use Change background opacity >, I could understand the ... in a label like Change background opacity to... >, but that means we now have ... used either to mean there is a subsequent dialog to complete the action, or that the label is incomplete. That's something I would avoid in menus.
Set the tab color... would be Change the tab color... (here the ... properly hint at the extra information to be requested before carrying out the action. Note that you sometimes refer to the tab as tab or as the tab, in Rename tab title and Set the tab color. It seems the should be used every time or never when referring to the same thing.

But as I said, I feel less strongly about this because the command panel is not a standard cascading menu UI element, so it doesn't necessarily imply the same UI consistency expectations.

This started as a request to fix a few items in the tab contextual menu and is turning into a whole UI style review. Sorry for starting this whole thing. I do feel Windows in general would benefit from more UI polishing though, so it's not just wasted time.

[HarshNarayanJha]

It's actually good! If a UI Style redesign would benefit all of the windows, it's doable. We just need a official conformation from Microsoft Staff about these refactors.

My latest commit is in line with these changes, and it's ready for merging

[HartJesse]

@HarshNarayanJha my discord is jesswurd

[Ismith507]

Hello, I'm currently working on a fix for this issue and had a quick question. When updating the capitalization, should colors with modifiers (e.g. "sea green") remain with both words capitalized? Thanks.

[HarshNarayanJha]

Hello, I'm currently working on a fix for this issue and had a quick question. When updating the capitalization, should colors with modifiers (e.g. "sea green") remain with both words capitalized? Thanks.

Since they are fully qualified colour (or color if you are american) names, I think they should be both capital.

[Ismith507]

Thanks!