Define and apply guidance about quick pick titles and placeholders

[jrieken]

Testing #158798 but actually noticeable across our whole UI. It is sad to see a mix of quick pick with and without title and placeholder. Worst, sometimes the title part is used like a placeholder and vice versa. This seems to be based off developer preference and not rules. We should define

• what to use as placeholder text and if it ever should be empty
• when and what for to use the title

Command picker

ssh connection

Continue on...

[kieferrm]

Agreed that we need to add this to our UX guidance.

From my perspective, placeholders are lightweight but they are low contrast and that you need to read them in full before you start typing. The first screenshot, for example, tells me what I can add once I typed the file name, but I can't see it anymore once I typed the first letter. Titles also provide context that is helpful when a QP was opened not with a keyboard shortcut but from a different UI elements (action button, link, etc.) that can be pretty far away from where the QP shows up.

[roblourens]

I've always liked the minimalism of the placeholder text but also sometimes get annoyed that it disappears while typing. But if something that I use 1000 times a day like the quickopen suddenly had a full title bar, that would be annoying and too "heavy" even though it might benefit new users.

Here and in the Continue On example, it seems like we are using the title as a dialog title and the placeholder as an extra detail.

If we want to consider new designs at all, what if we had a right-aligned placeholder that didn't disappear until the text you are typing reached it?

This also intersects with the conversation about the quick access experience because we talked about a placeholder that will change based on the mode you are in (quickopen, >, debug , etc)

[jrieken]

IMO shortcomings or dislikes of the placeholder text aren't a reason to use the title, but are a reason to improve the placeholder UI. Tho, the placeholder should be mostly optional or encouraging and not be needed to orient myself. The title IMO should be used for context about what you are doing, esp in a multi QP flow. Maybe what's missing is the ability to show some more permanent hint - something that can explain what we are after, like the message of a modal dialog

[daviddossett]

Will work on guidance here in the next iteration as a continuation of the Command Center/Quick Pick work in #155458, #158638, and #158064

[bpasero]

(I refer to "quick open" as the thing that drives commands, file search, pick via prefixes and "quick pick" as the widget and other usages)

Yes, guidelines make sense 👍

The reasons for quick open to not use title are quite easy, at the time we added quick open, there was no support for title at all.

I think we have added title area to the quick pick when we started to turn them more into dialog-like, wizard style widgets (@chrmarti ?) that extensions were able to use via API to provide more context of the current step you are in. In this mode quick pick is styled more like a dialog with title and description and less like a lightweight picker. Especially when used as a wizard, the title gives nice context on what step you are and there I think it makes perfect sense.

My personal feeling is that adding a heavy title to the quick open is not ideal, especially because once you type one of the quick open handlers such as @ you change context and the title would either have to change or be removed entirely if it does not apply anymore.

As for the placeholder, I think the very definition of a input placeholder is that it goes away once you type, but it is as easy to get it back when you clear the input field.

My suggestion: use title area when the picker is like a dialog, with buttons or when it is a wizard. Use placeholder otherwise.

[daviddossett]

My first thoughts:

• ❌ Don't use titles on the core keyboard-driven command center modes (e.g. go to file, command palette, @, debug, etc. etc.). These are more akin to the now-ubiquitous command palettes we see everywhere (GH, Vercel, Teams, etc.) and don’t need an explicit title.
• ✅ Do use titles on just about everything else since they are mostly functioning as dialogs asking for input or selection. Many of these are obvious, but many more rely on placeholder text to describe their purpose. They are also often opened from far away UI instead of a keybinding.
• Adjust placeholder text across the board to give hints as to the purpose of the text input (e.g. filtering, entering a url) and not to describe the purpose of the quick pick.
• Update title styling to make a smoother transition between title and no title

I totally get the concern w/ added visual weight if we are increasing the usage of titles. However, there are countless examples of quick picks without titles that are leaning on using placeholder text for a title (an anti-pattern IMO) which makes them hard to understand at a glance.

Demo

quick-pick-titles.mp4

Prior art

I liked this example from Figma which shows three UI surfaces with different purposes/weight:

• Quick actions (like our command palette/center)
• Lightweight dialog-like UI to capture input (like many of our quick picks e.g. creating a settings profile)
• Full blocking dialog w/ destructive action (like our existing dialogs

CleanShot.2022-10-27.at.10.50.48.mp4

[jrieken]

Do use titles on just about everything else since they are mostly functioning as dialogs asking for input or selection.

Unsure about that. To me it feels like repetition of the action that I just have clicked, like "Change Icon Theme" and then the title repeats just that. I would have not expected anything else TBH. There is also the confusion that these commands can be triggered from the command palette, meaning I open the command palette (no title), select "Change Icon Theme", and now see a title (which causes a visual shift)

[daviddossett]

To me it feels like repetition of the action that I just have clicked, like "Change Icon Theme" and then the title repeats just that. I would have not expected anything else TBH

I hear you, but isn't that how a dialog or modal would work? To me we are using a CLI-like interface in a dialog-like way. It would be like macOS using Spotlight to capture input instead of a dialog. The two feel fundamentally different. Today we burden the placeholder with providing the title which can work but often doesn't. Also consider the many cases they are triggered from icon buttons where you might not see the tooltip.

There is also the confusion that these commands can be triggered from the command palette, meaning I open the command palette (no title), select "Change Icon Theme", and now see a title (which causes a visual shift)

That happens today with many quick picks. E.g. Open Remote Repository -> <quick pick with title>. To me it's even more confusing to have this case-by-case logic applied to when we use titles vs. when we don't. That's why I'm trying to arrive at something much more deterministic.

I'm open to other ideas. But I think I'd rather solve for the UI transition challenge rather than have a really inconsistent experience across various quick picks.

[daviddossett]

After hearing feedback here, standup, and the UX sync, I think I've arrived at defaulting to not using titles unless there are good reasons to do so vs. the other way around. I have a few PRs going to reduce titles where they aren't needed and to polish or add missing placeholders across various core and extension-owned quick picks.

Boiling it down, this is where the conversations left off:

• ✅ Do use a title for multi-step quick picks
• ✅ Do use a title for quick picks w/o an input (e.g. Customize Layout)
• ✅ Do use a title for quick picks asking for text input (especially when the placeholder is giving a more detailed hint or example)
• ✅ Do use a title for quick picks featuring global buttons (e.g. Refresh on the python interpreter quick pick)
• ❌ Don't use a title for the command palette (search, commands, debug, etc.)
• ❌ Don't use a title when the placeholder can describe the purpose on its own (e.g. Select Color Theme)
• ❌ Don't use inputs without a placeholder

[bpasero]

Don't use a title when the placeholder can describe the purpose on its own

💯

[daviddossett]

Did an initial pass to update usage of titles in core via #165267 and remote-ssh via https://github.com/microsoft/vscode-remote-ssh/pull/265.

Also added guidance to extension UX guidelines: microsoft/vscode-docs@e7daf34.