2015 Visual Studio User Experience Guidelines RC Preview

Visual Studio User Experience Guidelines
2015 RC PREVIEW
MI C R O S O F T V I S U A L S T U D I O P A R T N E R P R E V I E W C O P Y . S U B J E C T T O C H A N G E .
QUESTIONS OR FEEDBACK? CONTACT US AT UXBOARD@MICROSOFT.COM
Welcome
The Visual Studio User Experience Guidelines are intended for those who design new features for Visual Studio. These
guidelines contain information about common user models and interaction patterns so that designers of new user
interfaces (UI) can create user experiences that are seamless and consistent within the development environment.
Developing software for Microsoft products means understanding the guidance provided by Windows. Important
resources to be aware of:
The Windows User Experience Interaction Guidelines are the basics for Windows desktop behavior and
appearance.
These Visual Studio User Experience Guidelines are specific to Visual Studio and supersede the general Windows
guidelines wherever appropriate to our environment.
The patterns and guides for Windows Store apps are a reference for emerging patterns that may be used in some
instances within Visual Studio.
About these guidelines

These guidelines give you information about what to do when designing for Visual Studio. In some cases, information
about how to do it is also included. For more detailed implementation information and to learn about specific APIs that
allow you to write code for solutions that integrate into the Visual Studio IDE, use the Visual Studio SDK.
Sections and topics

1.
2.
UX Essentials: Best practices, Anti-patterns,
8.
Layout: Dialog layout
and Dev14 UX principles
9.
Notifications and Progress: Notification systems,
Fonts and Formatting: The environment font

and Text style
3.
HDPI displays, Validating for HDPI displays, and
The VSColor service, Shared colors, Creating new color
Addressing DPI issues
tokens, Color value reference, Choosing High Contrast
11. Accessibility: Accessibility
colors, Using themed controls, Exposing colors for end
12. Animations: Animation fundamentals
4. Images and Icons: Image use in Visual Studio,

Visual Language Dictionary, Icon design, Using color
in images, and Icon theming and inversion
Menus and Commands: Command usage,
Naming commands, and Access and shortcut keys
6.
UI Text and Help: UI text and terminology,

Error messages, and Accessing Help
7.
10. HDPI Requirements: Requirements for supporting
Colors and Styling: Using color in Visual Studio,
users, and Daytona and web UI
5.
Progress indicators, Infobars, and Error validation
Interaction Patterns: Visual Studio patterns overview,

Window interactions, Tool windows, Document editor
conventions, Dialogs, Projects, Common controls
(Search, Text controls, Buttons and hyperlinks,
Lists and grids, and Tree views), On-object UI and
peeking, Selection models, Persistence and saving
settings, and Touch input
and Animation patterns

13. World Readiness: World readiness
14. Evaluation Tools: Craftsmanship checklist
1: UX Essentials

2015 RC PREVIEW
UX Essentials: Best practices

Screen resolution
Minimum resolution
The minimum resolution for Visual Studio Dev14 is 1280x1024. This means that it is possible to use Visual Studio at this
resolution, although it might not be an optimal user experience. There is no guarantee that all aspects will be usable at
resolutions lower than 1280x1024.
Initial dialog size should not exceed 1000 pixels in height so as to fit within the frame of the integrated development
environment (IDE) within this minimum resolution at 96 dpi.
High-density displays
UI in Visual Studio must work well in all DPI scaling factors that Windows supports out of the box: 150%, 200%, and 250%.
Review the high-DPI guidelines (detailed further in 10: High-Density Display Requirements) for more detailed information
and an explanation about how to validate your UI for high-DPI situations.
Basic principles
1.
Be consistent within the Visual Studio environment.

Follow existing interaction patterns within the shell. (7: Interaction Patterns)
Design interface details to be consistent with the shell's visual language and craftsmanship requirements.
(14: Evaluation Tools)
Use shared commands and controls when they exist.
Understand the Visual Studio hierarchy and how it establishes context and drives the UI.
2.
Use the environment service for fonts and colors.

All UI should respect the current environment font setting, unless it is exposed for customization in the Fonts
and Colors page in the Options dialog. (2: Fonts and Formatting)
UI elements must use the VSColor service, using shared environment tokens or feature-specific tokens.
(3: Colors and Styling)
3.
Make all imagery consistent with the new Visual Studio style.
Follow Visual Studio design principles for icons, glyphs, and other graphics. (4: Images and Icons)
Do not place text in graphic elements.
4. Design from a user-centric perspective.

Create the task flow before the individual features within it.
Be familiar with your users and make that knowledge explicit in your spec.
When reviewing the UI, evaluate the complete experience as well as the details.
Design your UI so that it remains functional and attractive regardless of locale or language.
(13: World Readiness)
2 Visual Studio UX Guidelines: UX Essentials

EARLY PARTNER PREVIEW OF 2015 GUIDELINES . SUBJECT TO CHANGE. FOR QUESTIONS OR FEEDBAC K, EMAIL UXBOARD@MICROSOFT.COM.
UX Essentials: Anti-patterns
Visual Studio contains many examples of UI that follow our guidelines and best practices. In an effort to be consistent,
developers often borrow from product UI design patterns similar to what they're building. Although this is a good
approach that helps us drive consistency in user interaction and visual design, we do on occasion ship features with a few
details that do not meet our guidelines due to schedule constraints or defect prioritization. In these cases, we do not want
teams to copy one of these "anti-patterns" because they proliferate bad or inconsistent UI within the Visual Studio
environment.
This document is not an exhaustive list of anti-patterns within Visual Studio. If you have any questions about a feature
design that you want to leverage and are unsure of whether it is sanctioned, the UxBoard is always available to answer
your questions.
Required fields/settings shown in error state by default

Feature team goals
Warn users that they have added an element that must be configured.
Draw the users attention to the areas that need input.
Anti-pattern solution
As soon as the user has initiated an action and before they have completed the task, immediately place critical-stop icons
next to the areas that need configuration.
Example: Manifest Designer declarations

Adding a declaration to the list immediately places it in an
error state, which persists until the user sets the required
properties. In this case, there is an additional concern
because the icon used for the alert contains an X, so the
common remove icon cannot be used beside it. As a
result, the UI uses a Remove button, a more clunky
control.
Result
The user is left feeling that adding a declaration has
created an error, when the intended message is simply
that theyve started a task and not yet finished it. This not
only causes visual noise but is inconsistent with common
UI, in which validation is done with focus change and not before.
Alternatives
Better solutions to this problem would be to:
Allow the user to add a declaration without warning and then move immediately to set properties on the item.
Add the warning icon (gold triangle) when focus moves from the item, such as to add another declaration to the
list or to attempt to change tabs within the designer.
Pop up a dialog if the user attempts to change tabs before setting properties on any declarations. Explain that the
application will not build (or whatever the implications) until the warnings are resolved. If the user dismisses the
dialog and changes tabs anyway, then an icon (critical or warning, as appropriate) is added to the Declarations
tab.
Visual Studio UX Guidelines: UX Essentials 3
EARLY PARTNER PREVIEW OF 2015 GUIDELINES. SUBJECT TO CHANGE. FOR QUESTIONS OR FEEDBAC K, EMAIL UXBOARD@MICROSOFT.COM.
Multiple clicks to dismiss UI

Feature team goal
Dont allow the user to dismiss the UI without first seeing the
explanation text.
Anti-pattern
The team inserting video links into various places within Visual
Studio Ultimate decided against the common pattern of an X
close button and tooltip explanation as specified by the UX
team, and instead implemented a dropdown and Dont show
this again link.
Result
Instead of a simple close button (one click), the user is forced
to use two clicks to simply dismiss the UI in every place that
the video links appear.
Alternatives
Incorrect: forcing the user to read explanatory text before

dismissing UI is an anti-pattern within Visual Studio.
The correct design for this situation would be to follow the

pattern common to Internet Explorer, Office and Visual Studio:
the user can see the tooltip description on hover, and one click
hides the UI.
Correct: as designed, video links should display a tooltip with

additional information on hover, and clicking the X should
dismiss the message without need for further interaction.

Using command bars for settings
Figure A: Anti-pattern
Figure B: Better, but still an anti-pattern
Figure C: Correct use of Visual Studio pattern
Figure A represents this anti-pattern: putting a setting underneath a command button that applies to more than just that
command. In this sketch, there are commands besides Start Debugging like View in Browser, Start Without Debugging,
and Step Into that will respect the selected setting.
Slightly better, but still undesirable, is putting settings of this type in the toolbars, as shown in Figure B. While split
buttons take less space and therefore are an improvement over drop-downs, both designs are still using a toolbar to
promote something that isn't really a command.
In Figure C, the setting is tied to a series of commands. There is no global setting being set and we're just switching
between four commands. This is the only situation in which commands in the toolbar are acceptable.

Control anti-patterns
Some anti-patterns are simply incorrect usage or presentation of a control or group of controls.
Underlining used as a group label, not a hyperlink

Underlining text should be used only for hyperlinks.
Bad:
Good:
Clicking on a check box results in a pop-up dialog
Clicking the 'Enable Remote Desktop for all roles' check box in the 'Publish Windows Azure Application'
wizard immediately brings up a pop-up dialog, a Visual Studio anti-pattern. In addition, the check box
field does not fill with a checkmark after being selected, another interaction anti-pattern.

Hyperlink anti-patterns
The following example contains two anti-patterns.
1.
2.
The foreground turning red on hover means that the correct shared color from the font service is not being used.
Learn more is not the appropriate text for a link to a conceptual topic. The users goal is not to learn more, it is
to understand the ramifications of their choice.
Both the color choice and wording of this hyperlink are Visual Studio anti-patterns.
Alternative
Pose the question that the user would be asking by clicking the link:
How do Windows Azure Mobile Services work?
When do I need a Windows Azure Mobile Service project?
Using 'Click here' or 'Click here' for links

Hyperlinks should be self-descriptive. It is an anti-pattern to use Click here or any similar variation.
Bad:
Click here for instructions about
how to create a new project.
Good:
How do I create a new project?

UX Essentials: Dev14 UX principles

All major businesses within Microsoft have made the decision to align behind a shared set of "modern" design principles.
In keeping with this decision, these businesses have taken further steps to establish a sense of shared visual design
direction and common experience patterns. Visual Studio follows the shared Microsoft design principles and the UX team
has adapted them to be specific to our product and users. We use these principles to guide and evaluate divisional design
efforts in designing a "best-of-breed" modern application.
Pride in craftsmanship
Demonstrate craftsmanship within our own tools and services that sets a great example for developers who use
Visual Studio as a reference when building their own applications.
Prioritize and maintain a high bar for resolving craftsmanship issues that negatively impact the experience of
building and designing modern apps and services.
Engineer the experience to be complete, thorough, and polished at every stage.
Be fast and fluid
Design task flows that feel smooth, with steps seamlessly connected to what comes before and after.
Ensure that tool windows and information presented to the user are consistent with their current context.
Deliver experiences that are more contextually aware. For example, recreate the context associated with an asset
whenever that asset is reopened.
Authentically digital
Be true to the capabilities of hardware, software, and services.

Ensure that each feature is optimal for a specific task.
Make sure that design decisions are validated with real users, completing real tasks, on the real platform and
hardware.
Do more with less
Make the experience great at something, not mediocre at lots of things.

Pursue the minimal design for each experience by focusing on features or concepts that directly contribute to its
core viability.
Use pixels sparingly and fiercely reduce administrative UI wherever possible.
Win as one
Optimize for the overall experience even if that requires local sacrifices.
Adopt the appropriate shared design patterns to ensure that cross-partnership experiences are cohesive and
jointly successful.

2: Fonts and Formatting

2015 RC PREVIEW
Fonts and Formatting: The environment font

All fonts within Visual Studio must be exposed to the user for customization. This is primarily done through the Fonts and
Colors page in the Tools > Options dialog. The three main categories of font settings are:
Environment font the primary font for the IDE (integrated development environment), used for all interface
elements including dialogs, menus, tool windows, and document windows. By default, the environment font is tied
to a system font that appears as 9 pt Segoe UI in current versions of Windows. Using one font for all interface
elements helps ensure a consistent font appearance throughout the IDE.
Text editor elements that surface in the code editor and other text-based editors can be customized in the Text
Editor settings in Tools > Options.
Specific collections designer windows that offer user customization of their interface elements may expose fonts
specific to their design surface in their own settings page in Tools > Options.
Editor font customization and resizing

Users often will enlarge or zoom the size and/or color of text in the editor according to their preference, independent of
the general user interface. Because the environment font is used on elements that might appear within or as part of an
editor/designer, it is important to note the expected behavior when one of these font classifications is changed.
When creating UI elements that appear in the editor but are not part of the content, it is important to use the environment
font and not the text font that elements resize in a predictable way.
1.
2.
For code text in the editor, resize with the code text font setting and respond to the editor texts zoom level.
All other elements of the interface should be tied to the environment font setting and respond to any global
changes in the environment. This includes (but is not limited to):
Text in context menus
Text in an editor adornment, such as light bulb menu text, quick find editor pane, and navigate to pane
Label text in dialog boxes, such as Find in Files or Refactor
Accessing the environment font

In Native or WinForms code, the environment font can be accessed by calling the method IUIHostLocale::GetDialogFont
after querying the interface from the SID_SUIHostLocale service. For Windows Presentation Foundation (WPF), derive your
dialog window class from the shell's DialogWindow class instead of WPF's Window class.
In XAML, the code looks like this:
<ui:DialogWindow
x:Class="MyNameSpace.MyWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:ui="clrnamespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.11.0"
ShowInTaskbar="False"
WindowStartupLocation="CenterOwner"
Title="My Dialog">
</ui:DialogWindow>
Code behind:
internal partial class WebConfigModificationWindow: DialogWindow
{
}
(Replace Microsoft.VisualStudio.Shell.11.0 with the current version of the MPF dll.)

10 Visual Studio UX Guidelines: Fonts and Formatting
EARLY PARTNER PREVIEW OF 2015 GUIDELINES. SUBJECT TO CHANGE. FOR QUESTIONS OR FEEDBACK, EMAIL UXBOARD@MICROSOFT.COM.
To display the dialog, call "ShowModal()" on the class over ShowDialog(). ShowModal() sets the correct modal state in
the shell, ensures the dialog is centered in the parent window, and so on.
The code is as follows:
MyWindow window = new MyWindow();
window.ShowModal();
ShowModal returns a bool? (nullable Boolean) with the DialogResult, which can be used if needed. The return value is true
if the dialog was closed with OK.
If you need to display some WPF UI that is not a dialog and is hosted in its own HwndSource, such as a popup window or
a WPF child window of a Win32/WinForms parent window, you will need to set the FontFamily and FontSize on the root
element of the WPF element. (The shell sets the properties on the main window, but they will not be inherited past a
HWND). The shell provides resources the properties can be bound to, like this:
<Setter Property="FontFamily" Value="{DynamicResource VsFont.EnvironmentFontFamily}" />
<Setter Property="FontSize" Value="{DynamicResource VsFont.EnvironmentFontSize}" />
Formatting (scaling/bolding) reference

Some dialogs require particular text to be bold or a size other than the environment font. Previously, fonts larger than the
environment font were coded as "environment font +2" or similar. While that method will continue to work, using the
provided code snippets will support high-DPI monitors and ensure that display text always appears at the correct size and
weight (such as Light or Semilight).
Note: Before you apply formatting, ensure that you are following the guidance found in Text style.
To scale the environment font, set the style of the TextBlock or Label as indicated. Each of these code snippets, properly
used, will generate the correct font, including the appropriate size and weight variations.
Where "vsui" is a reference to the namespace Microsoft.VisualStudio.Shell:
xmlns:vsui="clr-namespace:Microsoft.VisualStudio.Shell;assembly=Microsoft.VisualStudio.Shell.14.0"
375% Environment font + Light

Appears as: 34 pt Segoe UI Light
Use for: (rare) unique branded UI, such as in the Start Page
Procedural code: Where "textBlock" is a previously defined TextBlock and "label" is a previously defined Label:
textBlock.SetResourceReference(TextBlock.StyleProperty,
VsResourceKeys.TextBlockEnvironment375PercentFontSizeStyleKey);
label.SetResourceReference(Label.StyleProperty,
VsResourceKeys.LabelEnvironment375PercentFontSizeStyleKey);
XAML: Set the style of the TextBlock or Label as shown:
<TextBlock Style="{DynamicResource {x:Static
vsui:VsResourceKeys.TextBlockEnvironment375PercentFontSizeStyleKey}}">TextBlock: 375
Percent Scaling</TextBlock>
<Label Style="{DynamicResource {x:Static
vsui:VsResourceKeys.LabelEnvironment375PercentFontSizeStyleKey}}">Label: 375 Percent
Scaling</Label>
Visual Studio UX Guidelines: Fonts and Formatting 11

310% Environment font + Light

Appears as: 28 pt Segoe UI Light
Use for: large signature dialog titles, main heading in reports
Scaling</Label>
200% Environment font + Semilight

Appears as: 18 pt Segoe UI Semilight
Use for: subheadings, titles in small and medium dialogs
Scaling</Label>
155% Environment font

Appears as:14 pt Segoe UI
Use for: section headings in document well UI or reports
Scaling</Label>
122% Environment font

Appears as: 11 pt Segoe UI
Use for: section headings in signature dialogs, top nodes in tree view, vertical tab navigation
Scaling</Label>
Environment font + bold

Appears as: Bolded 9 pt Segoe UI
Use for: Labels and subheads in signature dialogs, reports, and document well UI
VsResourceKeys.TextBlockEnvironmentBoldStyleKey);
VsResourceKeys.LabelEnvironmentBoldStyleKey);
<TextBlock x:Name="textBlock" Style="{DynamicResource {x:Static
vsui:VsResourceKeys.TextBlockEnvironmentBoldStyleKey}}">Bold TextBlock</TextBlock>
<Label x:Name="label" Style="{DynamicResource {x:Static
vsui:VsResourceKeys.LabelEnvironmentBoldStyleKey}}">Bold Label</Label>

Localizable styles
In some instances, localizers will need to modify font styles for different locales, such as removing bolding from text for
East Asian languages. To make the localization of font styles possible, those styles must be within the .resx file. The best
way to accomplish this and still edit font styles in the Visual Studio form designer is to explicitly set the font styles at
design time. Although this creates a full font object and might seem to break the inheritance of parent fonts, only the
FontStyle property is used to set the font.
The solution is to hook the dialog form's FontChanged event. In the font changed event, walk all controls and check if
their font is set. If it is set, change it to a new font based on the form's font and the control's previous font style. An
example of this in code is:
private void Form1_FontChanged(object sender, System.EventArgs e)
{
SetFontStyles();
}
/// <summary>
/// SetFontStyles - This function will iterate all controls on a page
/// and recreate their font with the desired fontstyle.
/// It should be called in the OnFontChanged handler (and also in the constructor
/// in case the IUIService is not available so OnFontChange doesn't fire).
/// This way, when the VS shell font is given to us the controls that have
/// a different style for the font (bolded for example) will recreate their font
/// and use the VS shell font but with a style variation (bolded ...).
/// </summary>
protected void SetFontStyles()
{
SetFontStyles(this, this, this.Font);
}
protected static void SetFontStyles(Control topControl, Control parent, Font referenceFont)
{
foreach(Control c in parent.Controls)
{
if (c.Controls != null && c.Controls.Count > 0) {
SetFontStyles(topControl, c, referenceFont);
}
if (c.Font != topControl.Font) {
c.Font = new Font(referenceFont, c.Font.Style);
}
}
}
Using this code guarantees that when the form's font is updated, the fonts of controls will update as well. This method
should also be called from the form's constructor, because the dialog might fail to get an instance of IUIService and the
FontChanged event will never fire. Hooking FontChanged will allow dialogs to dynamically pick up the new font even if
the dialog is already open.

Testing the environment font

To ensure that your UI is using the environment font and respects the size settings, open Tools > Options > Environment
> Fonts and Colors and select Environment Font under the Show settings for: dropdown menu.
Set the font to something very different than the default. To make it obvious which UI does not update, choose a font with
serifs (such as Times New Roman) and set a very large size. Then test your UI to ensure it respects the environment. Here
is an example using the license dialog:
In this case, User Information and Product Information are not respecting the font. In some cases this might be an
explicit design choice, but it can be a bug if the explicit font is not specified as a part of the redline specifications.
To reset the font, click Use Defaults under Tools > Options > Environment > Fonts and Colors.
Fonts and Formatting: Text style

Text style refers to font size, weight, and casing. This topic is about design. For implementation guidance,
see The environment font.
Text casing
All caps
Do not use all caps for titles or labels in Visual Studio.
All lowercase
Do not use all lowercase for titles or labels in Visual Studio.
Sentence and title case

Text in Visual Studio should use either title case or sentence case, depending on the situation.
Use title case for:
Dialog titles
Group boxes
Menu items
Context menu items
Buttons
Table labels
Column headers
Tooltips
Use sentence case for:

Labels
Check boxes
Radio buttons
List box items
Status bars
Title case
Title case is a style in which the first letters of most or all of the words within a phrase are capitalized. In Visual Studio, title
case is used for many items, including:
Tooltips
Example:
"Preview Selected Items"
Table field labels

Example:
"Browse to URL"
Column headers
Example:
"System Response"
Menu items
Example:
"Save All"
When using title case, refer to the following table for when to capitalize words and when to leave them lowercase:
Uppercase
Comments and examples
All nouns
All verbs
including "Is" and other forms of "to be"
All adverbs
including "Than" and "When"
All adjectives
including "This" and "That"
All pronouns
including the possessive "Its" as well as "It's," a

contraction of the pronoun "it" and verb "is"
First and last words, regardless of parts of speech

Prepositions that are part of a verb phrase
Such as in: "Closing Out All Windows" or "Shutting

Down the System"
All letters of an acronym
HTML, XML, URL, IDE, or RGB
The second word in a compound word if it is a noun or
Cross-Reference, Pre-Microsoft Software, Read/Write
proper adjective, or if the words have equal weight
Access, Run-Time

Lowercase
Examples
The second word in a compound word if it is another part of
How-to, Take-off
speech or a participle modifying the first word

Articles, unless one is the first word in the title
a, an, the
Coordinate conjunctions
and, but, for, nor, or
Prepositions with words of four or fewer letters outside of a
into, onto, as for, out of, on top of
verb phrase
To when used in an infinitive phrase
"How to Format Your Hard Disk"
Sentence case
Sentence case is the standard capitalization method for writing in which only the first word of the sentence is capitalized,
along with any proper nouns and the pronoun "I." In general, sentence case is easier for a worldwide audience to read,
especially when the content will be translated by a machine. Use sentence case for:
Status bar messages. These are simple, short, and provide only status information.
Example: Loading project file
All other UI elements, including labels, check boxes, radio buttons, and list box items.
Example: "Select all items in list"
Text formatting
Default text formatting in Visual Studio 2013 is controlled by an environment font service. This service helps ensure a
consistent font appearance throughout the IDE (integrated development environment), and you must use it to guarantee
a consistent experience for your users.
The default size used by the Visual Studio font service comes from Windows and appears as 9 pt. You can apply
formatting to the environment font. This topic covers how and where to use styles. For implementation information, refer
to The environment font.
Bold text
Bold text is used sparingly in Visual Studio and should be reserved for:
question labels in wizards

designating the active project in Solution Explorer
overridden values in the certain properties tool window
certain events in the Visual Basic editor dropdown lists
server-generated content in the document outline for web pages
section headers in complex dialog or designer UI
Italics
Visual Studio does not use either italic or bolded italic text.
Color
Blue is reserved for hyperlinks (navigation and commanding) and should never be used for orientation.
Larger headings (environment font x 155% or greater) can be colored for these purposes:
o
To provide visual appeal to signature Visual Studio UI
To call attention to a specific area
To offer relief from the standard dark gray/black environment text color
Color in headings should leverage existing Visual Studio brand colors, primarily the main purple, #FF68217A.
When using color in headings, you must adhere to the Windows color guidelines, including contrast ratio and
other accessibility considerations.
Font size
Visual Studio Dev14 UI design features a lighter appearance with more white space. Where possible, chrome and title bars
have been reduced or removed. While information density is a requirement in Visual Studio, typography continues to be
important, with an emphasis on more open line spacing and a variation of font sizes and weights.
The following tables includes design details and visual examples for the display fonts used in Visual Studio. Some display
font variations have both the size and weight, such as Light or Semilight, coded into their appearance. Do not use other
sizes, weights, or typefaces.
Implementation code snippets for all display fonts can be found in The environment font.
Headline 1: Environment font x 375% + Light
AaBbCcXxYyZz
Usage: Rare. Unique
In comps, appears as 34pt Segoe UI Light.
branded UI only.
Spec as: Environment font x 375% + Light.
Do:
-
Use sentence
case
Always use Light
weight
Visual example:
Currently not used. May be used in the Start Page.
Do not:
-
Use for UI other

than signature UI
such as Start
Page
Bold, italic, or
bold italic
Use for body
text
Use in tool
windows

Headline 2: Environment font x 310% + Light
AaBbCcXxYyZz
Usage:
In comps, appears as 28pt Segoe UI Light.
Spec as: Environment font x 310% + Light.
Larger heading in
signature dialogs
Main report
Visual example:
heading
Do:
-
Use sentence case

Always use Light
weight
Do not:
-
Use for UI other

than signature UI
such as Start Page
Bold, italic, or bold
italic
Use for body text
Use in tool
windows
Headline 3: Environment font x 200% + Semilight
AaBbCcXxYyZz
Usage:
In comps, appears as 18 pt Segoe UI Semilight.
Spec as: Environment font x 200% + Semilight.
Subheadings
Titles in small and
medium dialogs
Visual example:
Do:
-
Use sentence case

Always use
Semilight weight
Do not:
-

italic
Use for body text
Use in tool
windows

Headline 4: Environment font x 155%

AaBbCcXxYyZz
Usage:
In comps, appears as 14 pt Segoe UI.
Spec as: Environment font x 155%.
Section headings in
document well UI
Reports
Visual example:
Do:
-
Use sentence case
Do not:
-

italic
Use for body text
Use in standard VS
controls
Use in tool
windows
Headline 5: Environment font x 122%

AaBbCcXxYyZz
Usage:
Spec as: Environment font x 122%.
Section headings
in signature
dialogs
Top nodes in tree
view
Vertical tab
navigation
Visual example:
Do:
-
Use sentence
case
Do not:
-
Bold, italic, or
bold italic
Use for body text
Use in standard
VS controls
Use in tool
windows

Headline 6: Environment font + Bold

AaBbCcXxYyZz
Usage:
In comps, appears as bolded 9 pt Segoe UI.
Spec as: Environment font + Bold.
Labels and
subheads in
signature dialogs,
reports, and
document well UI
Visual example:
Do:
-
Use sentence
case
Use bold weight
Do not:
-
Italic or bold
italic
Use for body text
Use in standard
VS controls
Use in tool
windows
Body: Environment font

AaBbCcXxYyZz
Usage:
All other text
Spec as: Environment font.
Do:
-
Use sentence
case
Visual example:
Do not:
-
Italic or bold
italic

Padding and spacing

Headings require space around them to give them the appropriate emphasis. This space varies depending on point size
and what else is near the heading, such as a horizontal rule or a line of text in the environment font.
The ideal padding for a heading by itself should be 90% of the capital character height space. For example, a 28 pt
Segoe UI Light heading has a cap height of 26 pt, and the padding should be approximately 23 pt, or about 31
pixels.
The minimum space around a heading should be 50% of the capital character height. Less space may be used
when a heading is accompanied by a rule or other tight-fitting element.
Bolded environment font text should follow default line height spacing and padding.
Additional resources
-
MSDN: Fonts
MSDN: User interface text

3: Colors and Styling

2015 RC PREVIEW
Colors and Styling: Using color in Visual Studio

Color is an important element in most user interfaces, including Visual Studio. According to the Windows UX Guide:
Beyond pure aesthetics, color has associated meanings and elicits emotional responses. To prevent confusion in meaning,
color must be used consistently. To obtain the desired emotional responses, color must be used appropriately.
In Visual Studio, color is used primarily as a communication tool, not just as decoration. Use color minimally and reserve it
for situations where you want to:
Communicate meaning or affiliation (for example, platform or language modifiers)

Attract attention (for example, indicating a status change)
Improve readability and provide landmarks for navigating the UI
Increase desirability
Several options exist for assigning colors to UI elements in Visual Studio. Sometimes it can be difficult to figure out which
option youre supposed to use, or how to use it correctly. This series of articles will help you:
1.
2.
3.
Understand the different services and systems used to define colors in Visual Studio.
Select the correct option for a given element.
Correctly use the option you have chosen.
IMPORTANT: Never hardcode hex, RGB, or system colors to your UI elements. Using the services allows for flexibility
in tuning hue. Additionally, without the service, you will not be able to take advantage of the theme-switching
capabilities of the VSColor service and will either have to implement your own theme-switching method or your UI
might look inconsistent in Visual Studio.
24 Visual Studio UX Guidelines: Colors and Styling

Methods for assigning color to Visual Studio interface elements

Choose the method best suited to your UI elements:
Your UI
Method
What are they?
You have embedded or standalone
System colors
System names that allow the operating system to define the
dialog boxes.
color and appearance of the UI elements, such as for common

dialog controls
You have custom UI that you want to
Common shared colors
Existing predefined color token names for specific UI elements
Custom colors
Color token names that are specific to an area and not meant
be consistent with the overall VS

environment and you have UI
elements that match the category
and semantic meaning of the shared
tokens.
You have an individual feature or
group of features and there is no
to be shared with other UI
shared color for similar elements.

You want to allow the end user to
End-user customization
Settings defined in the Fonts and Colors page of the Tools >
customize UI or content (for example,
(Tools > Options dialog)
Options dialog or a specialized page specific to one UI feature
Daytona
Allows UI authored in HTML to access the color and font service
for text editors or specialized

designer windows).
You have UI that is authored in
HTML.
Visual Studio themes

Visual Studio features three different color themes: light, dark, and blue . It also detects High Contrast mode, which is a
system-wide color theme designed for accessibility. Users are prompted to select a theme during their first use of Visual
Studio and are able to switch themes later by going to Tools > Options > Environment > General and choosing a new
theme from the color theme drop-down menu.
Users can also use Control Panel to switch their entire systems into one of several High Contrast themes. If a user selects a
High Contrast theme, then the Visual Studio color theme selector no longer affects colors in Visual Studio, although any
theme changes are saved for when the user exits High Contrast mode. For more information about High Contrast mode,
see Choosing High Contrast colors.
Visual Studio UX Guidelines: Colors and Styling 25

Colors and Styling: The VSColor service

Visual Studio provides an environment color service, also called the VSColor service or the shell color service. This service
allows you to bind the color values of your UI elements to a name-value color set containing colors for each theme. The
VSColor service must be used for all UI elements, so that colors automatically change to reflect the current user-selected
theme, and so that UI bound to the environment color service will integrate with new themes in future versions of Visual
Studio.
There are two ways to use the VSColor service:
1.
2.
Use a named color token that has been predefined for the environment. See the Shared colors topic for more
details.
The benefit of this method is that your UI will always match common aspects of the IDE.
The downside of this method is that the set of colors is limited, and you are restricted to using these
colors in the same way that the shell does. If you dont use the colors correctly, you will have unexpected
results when the environment changes due to the addition of a new theme.
Design your own set of colors, give each color a token name, and add these definitions to your own theme color
XML file. The Color value reference topic can assist you in choosing colors, and the Creating new color tokens
topic will tell you how to add the colors to the service.
How the service works

The environment color service reads VSColors defined in the .pkgdef for the UI component. These VSColors are then
referenced in XAML markup or code and are loaded through either the IVsUIShell5.GetThemedColor or a
DynamicResource mapping.
Environment color service architecture

Accessing the service

There are several different ways to access the VSColor service, depending on what kind of color tokens you are using and
what kind of code you have.
Predefined environment colors

From native code
The shell provides a service that gives access to the COLORREF of the colors. The service/interface is:
IVsUIShell2::GetVSSysColorEx(VSSYSCOLOR dwSysColIndex, DWORD *pdwRGBval)
In the file VSShell80.idl, the enumeration __VSSYSCOLOREX has shell color constants. To use it, pass in as the index value
either one of the values from the enum __VSSYSCOLOREX documented in MSDN or a regular index number that the
Windows system API, GetSysColor, accepts. Doing this gets back the RGB value of the color that should be used in the
second parameter. If storing a pen or brush with a new color, you must AdviseBroadcastMessages (off of the Visual
Studio shell) and listen for WM_SYSCOLORCHANGE and WM_THEMECHANGED messages.
// To access the color service in native code, you'll make a call that resembles this:
pUIShell2->GetVSSysColorEx(VSCOLOR_COLOR_NAME, &rgbLOCAL_COLOR);
NOTE: The COLORREF values returned by GetVSSysColorEx() contain just R,G,B components of a theme color. If a
theme entry uses transparency, the alpha-channel value is discarded before returning. Therefore, if the environment
color of interest needs to be used in a place where transparency channel is important, you should use
IVsUIShell5.GetThemedColor instead of IVsUIShell2::GetVSSysColorEx, as described later in this topic.
From managed code

Accessing the VSColor service through native code is fairly straightforward. If you are working through managed code,
however, determining how to use the service can be tricky. Here is the process in C#:
private void VSColorPaint(object sender, System.Windows.Forms.PaintEventArgs e)
{
//getIVSUIShell2
IVsUIShell2 uiShell2 = Package.GetService(typeof(SVsUIShell)) as IVsUIShell2;
Debug.Assert (uiShell2 != null, "failed to get IVsUIShell2");
if (uiShell2 != null)
{
//get the COLORREF structure
uint win32Color;
uiShell.GetVSSysColorEx(VSSYSCOLOREX.VSCOLOR_SMARTTAG_HOVER_FILL, out win32Color);
//translate it to a managed Color structure
Color myColor = ColorTranslator.FromWin32((int)win32Color);
//use it
e.Graphics.FillRectangle(new SolidBrush(myColor), 0, 0, 100, 100);
}
}
If you are working in Visual Basic, use:
Dim myColor As Color = ColorTranslator.FromWin32((Integer)win32Color)

From WPF UI
You can bind to Visual Studio colors through values exported into the Application's ResourceDictionary. Below is an
example of using resources from the color table as well as binding to the environment font data in XAML.
<Style TargetType="{x:Type Button}">
<Setter Property="TextBlock.FontFamily"
Value="{DynamicResource VsFont.EnvironmentFontFamily}" />
<Setter Property="TextBlock.FontSize"
Value="{DynamicResource VsFont.EnvironmentFontSize}" />
<Setter Property="Background"
Value="{DynamicResource VsBrush.EnvironmentBackgroundGradient}" />
</Style>
New color tokens

Consuming VSColors from WPF XAML
If you are consuming VSColors from WPF UI, you can
use the Theme Editor Tools View Resource Code
button to create a C# class that will make it easy to
access your resources.
You can then copy the generated class to be compiled
as part of your project. It doesn't matter what class
name or namespace you use, because you are free to
change that when you put this code into your project.
This auto-generated class is intended to make it easy to
consume the resources you've defined from XAML.
For example, one might use XAML like this to access a
new SelectedItem color:
<UserControl xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:res="clr-namespace:SolutionExplorer.Resources" />
<TextBlock Background="{DynamicResource {x:Static res:SolutionExplorerColors.SelectedItemBrushKey}}"
Foreground="{DynamicResource {x:Static res:SolutionExplorerColors.SelectedItemTextBrushKey}}" />
At runtime, Visual Studio will dynamically bind to the correct brush values for your colors.
Consuming VSColors from non-WPF UI

If you have non-WPF UI or need to access color values directly, you can use IVsUIShell5.GetThemedColor. Color values
should be re-read from this service every time the theme changes. During theme changes, WM_THEMECHANGED or
WM_SYSCOLORCHANGE messages are broadcast to subscribers of IVsShell.AdviseBroadcastMessages. The class
VSColorTheme provides a way to be notified of the change by listening to the ThemeChanged event.
Use IVsUIShell5.GetThemedColor instead of IVsUIShell2::GetVSSysColorEx

The Visual Studio 2010 Environment Color Service used IVsUIShell2.GetVSSysColorEx to map VSColors to your UI. This
method has been replaced by IVsUIShell5.GetThemedColor in Visual Studio 2012. Code that uses GetVSSysColorEx will
continue to function, but it will only be able to access the VSColors that were defined in Visual Studio 2010, and the color
values returned dont contain the transparency channel. Additionally, you will not be able to access new colors defined in
Visual Studio 2012 or your VSPackage.
Helper classes and methods for managed code

For managed code, the shells Managed Package Framework library (Microsoft.VisualStudio.Shell.12.0.dll) contains a
couple of helper classes facilitating the use of themed colors. The helper methods in the
Microsoft.VisualStudio.Shell.VsColors class in MPF include GetThemedGDIColor() and GetThemedWPFColor(). Those
helper methods return the color value of a theme entry as System.Drawing.Color or System.Windows.Media.Color, to be
used in WinForms or WPF UI.
IVsUIShell5 shell5;
Button button = new Button();
button.BackColor = GetThemedGDIColor(shell5, SolutionExplorerColors.SelectedItemBrushKey);
button.ForeColor = GetThemedGDIColor(shell5,
SolutionExplorerColors.SelectedItemTextBrushKey);
///
///
///
///
///
///
<summary>
Gets a System.Drawing.Color value from the current theme for the given color key.
</summary>
<param name="vsUIShell">The IVsUIShell5 service, used to get the color's value.</param>
<param name="themeResourceKey">The key to find the color for.</param>
<returns>The current theme's value of the named color.</returns>
public static System.Drawing.Color GetThemedGDIColor(this IVsUIShell5 vsUIShell,

ThemeResourceKey themeResourceKey)
{
Validate.IsNotNull(vsUIShell, "vsUIShell");
Validate.IsNotNull(themeResourceKey, "themeResourceKey");
byte[] colorComponents = GetThemedColorRgba(vsUIShell, themeResourceKey);
// Note: The Win32 color we get back from IVsUIShell5.GetThemedColor is ABGR
return System.Drawing.Color.FromArgb(colorComponents[3], colorComponents[0],
colorComponents[1], colorComponents[2]);
}
private static byte[] GetThemedColorRgba(IVsUIShell5 vsUIShell, ThemeResourceKey
themeResourceKey)
{
Guid category = themeResourceKey.Category;
__THEMEDCOLORTYPE colorType = __THEMEDCOLORTYPE.TCT_Foreground
if (themeResourceKey.KeyType == ThemeResourceKeyType.BackgroundColor ||
themeResourceKey.KeyType == ThemeResourceKeyType.BackgroundBrush)
{
colorType = __THEMEDCOLORTYPE.TCT_Background;
}
// This call will throw an exception if the color is not found
uint rgbaColor = vsUIShell.GetThemedColor(ref category, themeResourceKey.Name,
(uint)colorType);
return BitConverter.GetBytes(rgbaColor);
}
public static System.Windows.Media.Color GetThemedWPFColor(this IVsUIShell5 vsUIShell,
ThemeResourceKey themeResourceKey)
{
Validate.IsNotNull(vsUIShell, "vsUIShell");
Validate.IsNotNull(themeResourceKey, "themeResourceKey");
byte[] colorComponents = GetThemedColorComponents(vsUIShell, themeResourceKey);
return System.Windows.Media.Color.FromArgb(colorComponents[3], colorComponents[0],
colorComponents[1], colorComponents[2]);
}
The class can also be used to obtain VSCOLOR identifiers for a given WPF color resource key, or vice versa.
public static string GetColorBaseKey(int vsSysColor);
public static bool TryGetColorIDFromBaseKey(string baseKey, out int vsSysColor);
The methods of VsColors class query the VSColor service to return the color value each time they are invoked. To obtain a
color value as System.Drawing.Color, an alternative with better performance is to instead use the methods of the
Microsoft.VisualStudio.PlatformUI.VSThemeColor class, which caches the color values obtained from the VSColor service.
The class subscribes internally to shell broadcast messages events, and discards the cached value when a theme changing
event occurs. Also, the class provides a .NET-friendly event to subscribe to theme changes. Use the ThemeChanged event
to add a new handler, and use the GetThemedColor() method to obtain color values for the ThemeResourceKeys of
interest. A sample code could look like this:
public MyWindowPanel()
{
InitializeComponent();
// Subscribe to theme changes events so we can refresh the colors
VSColorTheme.ThemeChanged += VSColorTheme_ThemeChanged;
RefreshColors();
}
private void VSColorTheme_ThemeChanged(ThemeChangedEventArgs e)
{
RefreshColors();
// Also post a message to all the children so they can apply the current theme appropriately
foreach (System.Windows.Forms.Control child in this.Controls)
{
NativeMethods.SendMessage(child.Handle, e.Message, IntPtr.Zero, IntPtr.Zero);
}
}
private void RefreshColors()
{
this.BackColor = VSColorTheme.GetThemedColor(EnvironmentColors.ToolWindowBackgroundColorKey);
this.ForeColor = VSColorTheme.GetThemedColor(EnvironmentColors.ToolWindowTextColorKey);
}
protected override void Dispose(bool disposing)
{
if (disposing)
{
VSColorTheme.ThemeChanged -= this.VSColorTheme_ThemeChanged;
base.Dispose(disposing);
}
}

Colors and Styling: Shared colors

When you are designing UI that uses common Visual Studio shell elements, or you would like your interface element to be
consistent with similar features, use existing token names in package definition files to choose and assign colors. This
ensures that your UI stays consistent with the overall Visual Studio environment and that it updates automatically when
themes are added or updated. This article describes common UI elements and the token names that they use, which you
can reference when building similar UI. For specific information about how to access these color tokens, see The VSColor
service.
Make sure to use token names correctly:
Use token names based on function, not on the color itself. The common shared colors are associated with
specific interface elements and are only intended to be used for the same or similar features. For example, dont
reuse the color of a pressed combo box for a spinning progress animation just because you like the color. The
functions of the combo box and the animation are different, and if the color associated with the combo box
changes, it may no longer be an appropriate color for your animation element. Consistent use of color helps
orient your users and prevent confusion.
Use background and text colors in the correct combination. Background colors that are intended to be used
with text will have an associated text color. Dont use text colors other than what is specified for that background.
If there is not an associated text color, dont use that background color for any surface on which you expect to
display text. Other combinations of text and background colors may result in an unreadable interface.
Use control colors that are appropriate for their location. In certain states, some Visual Studio controls do not
have separate border and background colors. Instead, they pick up those colors from the surfaces behind them.
Make sure that you always use the token names that are appropriate for the location where you are placing the
control.
Shared color categories

Shared color tokens should only be used for UI that is intended for similar purposes. Category names are a good
indication of the type of area that the colors should be used in. Never mix and match tokens from different categories. The
current shared tokens are in these categories:
Command structures: Menus (Menu title, Menu); Command bars (Command bar group, Command icons, Combo box,
Drop-down, Split button, More options and Overflow buttons)
Document windows: Window frame; Document tabs (Open document tabs, Preview tab, Document overflow button)
Tool windows: Tool window frame; Tool window title bar (Title bar buttons); Tool window tabs; Auto-hide tabs
Common shared controls: Search box (Search drop-down lists); Hyperlink; Infobar; Scrollbar; Tree view; Button controls;
Check box controls; Drop-down/Combo box controls; Tabular data (grid) controls
Themed dialogs
Manifest Designer
Tagging: Tag; Glyph (close icon)
Shell: Background; Command shelf
Toolbox
NOTE: Do not use tokens found in the categories Start Page or Cider!

Command structures
Menus
Menus can occur at several places within Visual Studio 2013: the main menu bar, embedded in document or tool windows,
or on right-click in various locations throughout the IDE. Implementations of menus associated with other UI elements are
discussed in the section for the respective element. You should always use the standard menu implementation provided
by the Visual Studio environment. However, in some rare instances you might not have access to the standard Visual
Studio menus. In these situations, use the following token names to ensure that your UI is consistent with other menus in
Visual Studio.
Use
whenever you need to

create a custom menu.
when you have a new UI
component that you
want to match the VS
menus.
Do not use
the background color

alone. Always use the
background/foreground
combination as
specified.

Menu title
Menu titles consist of a background, a border, and the title text, as well as an optional glyph, usually when the menu is
found in a command bar.
Use
whenever you are creating a custom menu title.
Do not use
State
Component
Default
Menu title
Menu title with glyph

Hover
Menu title

Pressed
Menu title

Disabled
for anything that you dont want to always match the menu title.
in any background/foreground combination other than specified.
Element
Token name: Category.Color
Background
None
Foreground (Text)
Environment.CommandBarTextActive
Foreground (Glyph)
Environment.CommandBarMenuGlyph
Border
None
Background
Environment.CommandBarMouseOverBackgroundBegin
Foreground (Text)
Environment.CommandBarTextHover
Foreground (Glyph)
Environment.CommandBarMenuMouseOverGlyph
Border
Environment.CommandBarBorder
Background
Environment.CommandBarMenuBackgroundGradientBegin
Foreground (Text)
Foreground (Glyph)
Environment.CommandBarMenuMouseDownGlyph
Border
Environment.CommandBarMenuBorder
Background
None
Foreground (Text)
Environment.CommandBarTextInactive
Foreground (Glyph)
Border
None
Gradient stops for this token not used in themed UI.

Menu
An individual menu item consists of the menu text
and an optional icon, check box, or submenu
glyph. Its background and text color change on
hover. This color token is a
background/foreground pair.
Use
for any drop-down list that is launched

from a menu bar or command bar.
Do not use
State
for any drop-down list that occurs in

another context.
in any background/foreground
combination other than specified.
Component
Default
Element
Background
Environment.CommandBarMenuBackgroundGradient
Begin
Foreground (Text)
Foreground
Menu
(Submenu glyph)
Environment.CommandBarMenuSubmenuGlyph
Border
Environment.CommandBarMenuBorder
Icon channel
Checked
Selected
Hover
Menu item
background
Environment.CommandBarMenuIconBackground
Separator
Environment.CommandBarMenuSeparator
Shadow
Environment.DropShadowBackground
Checkmark
Environment.CommandBarCheckBox
Checkmark
background
Environment.CommandBarSelectedIcon
Icon background
Environment.CommandBarSelected
Icon border
Environment.CommandBarSelectedBorder
Background
Environment.CommandBarMenuItemMouseOver
Foreground (Text)
Environment.CommandBarMenuItemMouseOver
Foreground
Environment.CommandBarMenuMouseOverSubmenuGl
yph
(Submenu glyph)

State
Component
Hover
Checked
Selected
Disabled
Menu item
Element
Checkmark
Environment.CommandBarCheckBoxMouseOver
Checkmark
background
Environment.CommandBarHoverOverSelectedIcon
Icon background
Environment.CommandBarHoverOverSelected
Icon border
Environment.CommandBarHoverOverSelectedIconB
order
Foreground (Text)
Foreground
(Submenu glyph)
Environment.CommandBarMenuSubmenuGlyph
Checkmark
Environment.CommandBarCheckBoxDisabled
Checkmark
Checked
background
Environment.CommandBarSelectedIconDisabled

Command bars
The command bar can appear in multiple places within the Visual Studio IDE, most notably the command shelf and
embedded in tool or document windows.
In general, always use the standard command bar implementation provided by the Visual Studio environment. Using the
standard mechanism ensures that all visual details will appear correctly and that interactive elements, will behave
consistently with other Visual Studio command bar controls. However, if it is necessary for you to build your own
command bar, make sure you style it correctly using the following token names.
Use
Do not use
in places where you need an embedded command
bar but are unable to use the standard Visual
Studio command bar implementation.
for UI elements that are not similar to a command

bar.
for command bar components other than the
ones for which token names are specified.
Command bar group

A command bar group consists of a related set of command bar controls and might contain any number of buttons, split
buttons, drop-down menus, combo boxes, or menus. Colors for those controls are regulated by separate token names and
are discussed individually elsewhere in this guide. A separator line is used to divide a command bar group into related
subgroups.
Use
Do not use
in places where you need an embedded command
bar but are unable to use the standard Visual
Studio command bar implementation.
for UI elements that are not similar to a command

bar.
for command bar components other than the
ones for which token names are specified.
State
Element
Default
Background
Environment.CommandBarGradientBegin
Border
Environment.CommandBarToolBarBorder
Drag handle
Environment.CommandBarDragHandle
(No other states)
Separator
Environment.CommandBarToolBarSeparator
Environment.CommandBarToolBarSeparatorHighlight

Command icons
For help selecting or designing icons for your command bar buttons, see the topic on Icon design (4: Images and Icons).
Use
for any buttons that will be placed on a command bar.
Do not use
State
Component
Default
Standard
Selected
Hover and
keyboard
focused
Standard
Selected
Pressed
Standard
Disabled
Standard
for controls that have their own token names.

Element
Background
N/A (inherits from command bar background)
Foreground (Text)
Border
N/A
Background
Environment.CommandBarSelected
Foreground (Text)
Environment.CommandBarTextSelected
Border
Environment.CommandBarSelectedBorder
Background
Foreground (Text)
Border
Background
Environment.CommandBarHoverOverSelected
Foreground (Text)
Environment.CommandBarTextHoverOverSelected
Border
Environment.CommandBarHoverOverSelectedIconBorder
Background
Environment.CommandBarMouseDownBackgroundBegin
Foreground (Text)
Environment.CommandBarTextMouseDown
Border
Background
N/A (inherits from command bar background)
Foreground (Text)
Border
N/A
Gradient stops and values available, but not used in themed UI.
Combo box
Use ...
when building custom combo boxes.

when creating a command bar control that is similar
to a combo box.
Do not use
for anything you dont want always to match the

command bar UI.
when you have access to a styled combo box.
State
Component
Default
Input field
Drop-down button
Drop-down list
Hover
Input field
Element
Token Name: Category.Color
Background
Environment.ComboBoxBackground
Foreground (Text)
Environment.ComboBoxText
Border
Environment.ComboBoxBorder
Separator
No separator
Background
N/A (inherits)
Foreground (Glyph) Environment.ComboBoxGlyph

Background
Environment.ComboBoxPopupBackgroundBegin
Foreground (Text)
Environment.ComboBoxItemText
Border
Environment.ComboBoxPopupBorder
Background
Environment.ComboBoxMouseOverBackgroundBegin
Foreground (Text)
Environment.ComboBoxMouseOverText
Border
Environment.ComboBoxMouseOverBorder
Separator
Environment.ComboBoxMouseOverSeparator
Background
Environment.ComboBoxButtonMouseOverBackground
Drop-down button
Foreground (Glyph) Environment.ComboBoxMouseOverGlyph
Drop-down list
Background
(Outside)
Drop-down list
Focused
Input field
Drop-down button
Pressed
Input field
Drop-down button
Disabled
Input field
Drop-down button
Environment.ComboBoxMouseOverBackgroundBegin
Background (Item)
Environment.ComboBoxItemMouseOverBackground
Foreground (Text)
Environment.ComboBoxItemMouseOverText
Border (Outside)
Background
Environment.ComboBoxFocusedBackground
Foreground (Text)
Environment.ComboBoxFocusedText
Border
Environment.ComboBoxFocusedBorder
Separator
Environment.ComboBoxFocusedButtonSeparator
Background
Environment.ComboBoxFocusedButtonBackground
Foreground (Glyph) Environment.ComboBoxFocusedGlyph

Background
Environment.ComboBoxMouseDownBackground
Foreground (Text)
Environment.ComboBoxMouseDownText
Border
Environment.ComboBoxMouseDownBorder
Separator
Environment.ComboBoxMouseDownSeparator
Background
Environment.ComboBoxButtonMouseDownBackground
Foreground (Glyph) Environment.ComboBoxMouseDownGlyph

Background
Environment.ComboBoxDisabledBackground
Foreground (Text)
Environment.ComboBoxDisabledText
Border
Environment.ComboBoxDisabledBorder
Separator
No separator
Background
N/A
Foreground (Glyph) Environment.ComboBoxDisabledGlyph

Drop-down
Use
when you are creating custom drop-down list controls.
Do not use
State
Component
Default
Selection field
Drop-down button
Drop-down list
Hover
Selection field
Drop-down button
Drop-down list
Pressed
Selection field
Drop-down button
for anything that is not similar to a drop-down list.

for combo boxes or split buttons.
Element
Background
Environment.DropDownBackground
Foreground (Text)
Environment.DropDownText
Border
Environment.DropDownBorder
Separator
No separator
Background
None
Foreground (Glyph)
Background
Environment.DropDownGlyph
Environment.DropDownPopupBackgroundBegin
Foreground (Text)
Environment.ComboBoxItemText
Border
Environment.DropDownPopupBorder
Shadow
Background
Environment.DropDownMouseOverBackgroundBegin
Border
Environment.DropDownMouseOverBorder
Separator
Environment.DropDownButtonMouseOverSeparator
Background
Environment.DropDownButtonMouseOverBackground
Foreground (Glyph)
Environment.DropDownMouseOverGlyph
Background
(Menu item)
Environment.ComboBoxItemMouseOverBackground
Foreground (Text)
Environment.ComboBoxItemMouseOverText
Border (outside)
Border (Menu item)
Environment.ComboBoxItemMouseOverBorder
Background
Environment.DropDownMouseDownBackground
Foreground (Text)
Environment.DropDownMouseDownText
Border
Environment.DropDownMouseDownBorder
Separator
Environment.DropDownButtonMouseDownSeparator
Background
Environment.DropDownButtonMouseDownBackground
Foreground (Glyph)
Environment.DropDownMouseDownGlyph

Split button
Split buttons share many token names with other command bar controls, such as buttons, menus, and command bar text.
All necessary action and drop-down button token names are repeated here for convenience. Split button drop-down lists
are implementations of command bar menus.
Use
when you are building a custom split button.
Do not use
State
Default
Hover
Component
for other kinds of buttons.

Element
Background
None
Foreground (Text)
Foreground (Glyph)
Environment.CommandBarSplitButtonGlyph
Border
N/A
Separator
N/A
Background
Pressed
Foreground (Text)
Foreground (Glyph)
Environment.CommandBarSplitButtonMouseOverGlyph
Border
Separator
Environment.CommandBarSplitButtonSeparator
Background
Background
Environment.CommandBarMouseDownBackgroundBegin
Disabled
Foreground (Text)
Environment.CommandBarTextMouseDown
Foreground (Glyph)
Environment.CommandBarSplitButtonMouseDownGlyph
Border
Separator
N/A
Background
N/A
Foreground (Text)
Environment.ComboBoxItemTextInactive
Foreground (Glyph)
Border
None
Separator
N/A

More options and Overflow buttons

The More options button is used when a command bar group is customizable by either adding or removing related
command bar buttons. The Overflow button appears when a command bar is truncated due to lack of horizontal space,
and on click shows a menu containing the command bar buttons that cannot be displayed. Colors for these two buttons
are controlled by the same set of token names.
Use
for custom More options or Overflow buttons.
Do not use
State
for buttons that dont have similar functionality to a More options or Overflow button.
Component
Default
More
options
Overflow
Hover
More
options
Overflow
Pressed
More
options
Overflow
Element
Background
Environment.CommandBarOptionsBackground
Foreground (Glyph)
Environment.CommandBarOptionsGlyph
Background
Environment.CommandBarOptionsMouseOverBackgroundBegin
Foreground (Glyph)
Environment.CommandBarOptionsMouseOverGlyph
Background
Environment.CommandBarOptionsMouseDownBackgroundBegin
Foreground (Glyph)
Environment.CommandBarOptionsMouseDownGlyph

Document windows
There is no need to replicate document windows, because they are provided by the Visual Studio environment. However,
you might decide that you want to leverage the colors used in document windows so that your UI always appears
consistent with this part of the Visual Studio environment. When using document window color tokens, you must be
careful to use them only for similar elements, and always in pairs. If you do not do so, you will have unexpected results in
your UI.
Document window frame

Document windows can be either docked in the IDE or floating as a separate window. When a document window is
floating outside the IDE, it still sits in a document well, and has background, border, text, and tab colors that are the same
as when it is part of the IDE. However, the document sits inside a frame that has its own background, border, and text
colors. When tool windows are docked in the document well, they inherit the behavior and color for their tabs from
document window token names.
Docked document window
Floating document window
Use
anywhere you are creating UI that you want to match document windows.
Do not use
for any UI that you dont want to change automatically if the shell has a theme update. In this case, refer to Color
Value Reference and use the hues to create your own token names.
State
Component
Element
Default
Document: docked or floating
Background
Depends on document type
Foreground
(Text)
Frame: floating, focused
Border
Environment.ToolWindowBorder
Background
Environment.ToolWindowFloatingFrame
Foreground
(Text)
Foreground
Frame: floating, unfocused
Environment.RaftedWindowButtonActiveGlyph
Border
Environment.MainWindowActiveDefaultBorder
Border (Glyph)
Environment.RaftedWindowButtonActiveBorder
Background
Environment.ToolWindowFloatingFrameInactive
Foreground
(Text)
Border
Environment.MainWindowInactiveBorder
Environment.RaftedWindowButtonInactiveBorder
(Glyph)
Foreground
Set to transparent
Environment.RaftedWindowButtonHoverActive
(Glyph)
Environment.RaftedWindowButtonHoverActiveGlyph
Border (Glyph)
Environment.RaftedWindowButtonHoverActiveBorder
Background
Pressed
Environment.ToolWindowFloatingFrameInactive
Environment.RaftedWindowButtonInactiveGlyph
Background
Frame: floating, unfocused
Set to transparent
(Glyph)
Border (Glyph)
Frame: floating, focused
Environment.ToolWindowFloatingFrame
(Glyph)
Foreground
Hover
Depends on document type
(Glyph)
Foreground
Environment.RaftedWindowButtonHoverInactive
(Glyph)
Environment.RaftedWindowButtonHoverInactiveGlyph
Border (Glyph)
Environment.RaftedWindowButtonHoverInactiveBorder
Background
(Glyph)
Foreground
Environment.RaftedWindowButtonDown
(Glyph)
Environment.RaftedWindowButtonDownGlyph
Border (Glyph)
Environment.RaftedWindowButtonDownBorder

Document tabs
Document tabs sit in the tab channel to indicate which documents are currently open, along with which one is the current
selected or active document. Tool windows can also be docked in the document tab channel if the user places them there.
In this situation, they use the same tab colors as document windows. If you are creating UI that you want to always match
the document window colors (including theme updates or if new themes are installed), then reference these color tokens.
Use
anywhere you are creating UI that you want to match document tabs and automatically pick up
theme updates or new theme colors.
Do not use
for any UI that you dont want to change automatically when the shell has a theme update.
Open document tabs

Each open document has a tab in the document tab channel that displays its name. Documents can be either selected or
open in the background, and their tabs reflect these states:
The selected tab represents the document that is currently displayed in the document well. A selected tab has a
document border that extends across the top edge of the document well.
Background tabs are any document tabs that are not the currently selected tab. Once clicked, they become the
selected tab and acquire all background, border, and text colors from those token names.
Use
when you are creating custom document tabs.
Do not use
for provisional (preview) UI.

for any UI that you dont want to change automatically
if the shell has a theme update. In this case, refer to
Color Value Reference and use the hues to create your
own token names.
Selected tab
State
Focused
Unfocused
Component
Element
Background
Environment.FileTabSelectedGradientTop
Foreground (Text)
Environment.FileTabSelectedText
Border
Environment.FileTabSelectedBorder
Document border
Environment.FileTabDocumentBorderBackground
Background
Environment.FileTabInactiveGradientTop
Foreground (Text)
Environment.FileTabInactiveText
Environment.FileTabInactiveBorder
Border
Document border
Set to same color as background.
Environment.FileTabInactiveDocumentBorderBackg
round

Background tab
State
Component
Default
Element
Token Name: Category.Color
Background
Border
Environment.FileTabBackground
Environment.FileTabText
Environment.FileTabBorder
Background
Environment.FileTabHotGradientTop
Foreground (Text)
Environment.FileTabHotText
Environment.FileTabHotBorder
Foreground (Text)
Hover
Border
Preview tab
The preview tab appears on the right side of the document tab channel when the user clicks an item in the Solution
Explorer tool window. It acts as a preview of the document and also gives the user the option to keep the document open
on the left side of the document tab channel. Only one preview tab open can be open at a time. Preview tabs have both
background and selected states, like open tabs, and can be focused or unfocused in their active state.
Use
anywhere you are creating provisional preview and want

some element to match the current preview tab color.
Do not use
for any kind of document or tab that is not provisional

(preview).
for any UI that you dont want to change automatically if
the shell has a theme update. In this case, refer to the
hues in Color Value Reference to create your own token
names.
Selected tab
State
Focused
Component
Element
Background
Environment.FileTabProvisionalSelectedActive
Foreground (Text)
Environment.FileTabProvisionalSelectedActiveForegrou
nd
Environment.FileTabProvisionalSelectedActiveBorder
Border
Document border
Unfocused
Environment.FileTabProvisionalSelectedActiveBorder
Background
Environment.FileTabProvisionalSelectedInactive
Environment.FileTabProvisionalSelectedInactiveForegr
Foreground (Text)
ound
Environment.FileTabProvisionalSelectedInactiveBorder
Border
Document border
Environment.FileTabProvisionalSelectedInactiveBorder

Background tab
State
Component
Default
Hover
Element
Background
Environment.FileTabProvisionalInactive
Foreground (Text)
Border
Environment.FileTabProvisionalInactiveForeground
Environment.FileTabProvisionalInactiveBorder
Background
Environment.FileTabProvisionalHover
Foreground (Text)
Environment.FileTabProvisionalHoverForeground
Border
Environment.FileTabProvisionalHoverBorder
Document overflow button

The document overflow button is present if there are one or more documents open, regardless of whether there is vertical
space in the current configuration to fit all document tabs. The document overflow drop-down menu, which is controlled
by the CommandBarMenu colors, displays a list of all open documents, both visible and hidden, and the overflow glyph
changes depending on whether all the open documents are displayed in the tab channel.
Use
when you are creating a custom overflow button.
Do not use
State
Default
Hover
Pressed
Component
for UI that is not similar to an overflow button.

for command bar overflow buttons.
Element
Background
Environment.DocWellOverflowButtonBackground
Foreground (Glyph)
Environment.DocWellOverflowButtonGlyph
Border
N/A
Background
Environment.DocWellOverflowButtonMouseOverBackground
Foreground (Glyph)
Environment.DocWellOverflowButtonMouseOverGlyph
Border
Environment.DocWellOverflowButtonMouseOverBorder
Background
Environment.DocWellOverflowButtonMouseDownBackground
Foreground (Glyph)
Environment.DocWellOverflowButtonMouseDownGlyph
Border
Environment.DocWellOverflowButtonMouseDownBorder

Tool windows
There is no need to replicate tool windows, because they are provided by the Visual Studio environment. However, you
might decide that you want to leverage the colors used in tool windows so that your UI always appears consistent with
this part of the Visual Studio environment.
Use
anywhere you are creating UI
that you want to match tool
windows.
Do not use
for any UI that you dont

want to change automatically
if the shell has a theme
update. In this case, refer to
the hues in Color Value
Reference to create your own
token names.

Tool window frame

Tool windows in Visual Studio are used for many different tasks, and can exist in one of several different states. If a tool
window is open, it can be assigned to any of the four sides of the document area. Tool windows can also float outside of
the IDE, which allows them to be repositioned anywhere within the users screen. Floating windows always sit on top of the
IDE. Finally, tool windows can be docked as document windows and appear as a tab in the document well. Tool windows
that have been docked as document windows are colored in part using document window token names.
Use
anywhere you are creating UI that you want to
match tool windows.
Do not use
State
Component
Docked
Floating:
focused
Floating:
unfocused
for any UI that you dont want to change

automatically.
if the shell has a theme update. In this case, refer to
Color Value Reference and use the hues to create
your own token names.
Element
Background
Environment.ToolWindowBackground
Border
Background
Border
Environment.MainWindowActiveDefaultBorder
Background
Border
Environment.MainWindowInactiveBorder

Tool window title bar

The title bar border is not a true border, but a thick line across the top of the title bar. It does not have a token name for
its unfocused state.
Use
match tool windows.
Do not use
automatically if the shell has a theme update. In this
case, refer to Color Value Reference and use the
hues to create your own token names.
Shown in light theme to illustrate drag handle texture
State
Focused
Component
Element
Background
Environment.TitleBarActiveGradientBegin
Foreground
Unfocused
(Text)
Environment.TitleBarActiveText
Border
Environment.TitleBarActiveBorder
Drag handle
Environment.TitleBarDragHandleActive
Background
Environment.TitleBarInactiveGradientBegin
Foreground
(Text)
Environment.TitleBarInactiveText
Border
N/A
Drag handle
Environment.TitleBarDragHandle

Title bar buttons

Use
for buttons that use color tokens from the tool window title bars.
Do not use
State
Component
Default
Focused
Unfocused
Hover
Focused
Unfocused
Pressed
Focused
Unfocused
for buttons that appear in other locations.

Element
Background
N/A
Foreground (Glyph)
Environment.ToolWindowButtonActiveGlyph
Border
N/A
Background
N/A
Foreground (Glyph)
Environment.ToolWindowButtonInactiveGlyph
Border
N/A
Background
Environment.ToolWindowButtonHoverActive
Foreground (Glyph)
Environment.ToolWindowButtonHoverActiveGlyph
Border
Environment.ToolWindowButtonHoverActiveBorder
Background
Environment.ToolWindowButtonHoverInactive
Foreground (Glyph)
Environment.ToolWindowButtonHoverInactiveGlyph
Border
Environment.ToolWindowButtonHoverInactiveBorder
Background
Environment.ToolWindowButtonDown
Foreground (Glyph)
Environment.ToolWindowButtonDownActiveGlyph
Border
Environment.ToolWindowButtonDownBorder
Background
Environment.ToolWindowButtonDown
Foreground (Glyph)
Environment.ToolWindowButtonDownInactiveGlyph
Border
Environment.ToolWindowButtonDownBorder

Tool window tabs

Use
match tool window tabs.
Do not use

automatically if the shell has a theme update. In
this case, refer to Color Value Reference and use
the hues to create your own token names.
Selected tab
State
Component
Focused
Element
Background
Environment.ToolWindowTabSelectedTab
Foreground (Text) Environment.ToolWindowTabSelectedActiveText
Unfocused
Border
Environment.ToolWindowTabSelectedBorder
Background
Environment.ToolWindowTabSelectedTab
Foreground (Text) Environment.ToolWindowTabSelectedText

Border
Environment.ToolWindowTabSelectedBorder
Background tab
State
Component
Element
Default
Environment.ToolWindowTabGradientBegin
Background
Gradient stops set to the same color value in VS 2013.
Environment.ToolWindowTabGradientEnd
Foreground (Text)
Environment.ToolWindowTabText
Border
Environment.ToolWindowTabBorder
Hover
Environment.ToolWindowTabMouseOverBackgroundBegin
Background
Environment.ToolWindowTabMouseOverBackgroundEnd
Foreground (Text)
Border
Environment.ToolWindowTabMouseOverText
Environment.ToolWindowTabMouseOverBorder

Auto-hide tabs
Use
anywhere you are creating UI that you want to match auto-hidden tool window tabs.
Do not use
State
Default
Hover
Component
for any UI that you dont want to change automatically if the shell has a theme update.
In this case, refer to Color Value Reference and use the hues to create your own token
names.
Element
Background
Environment.AutoHideTabBackgroundBegin
Foreground (Text)
Environment.AutoHideTabText
Border
Environment.AutoHideTabBorder
Background
Environment.AutoHideTabMouseOverBackgroundBegin
Foreground (Text)
Environment.AutoHideTabMouseOverText
Border
Environment.AutoHideTabMouseOverBorder

Common shared controls

When you use a standard Visual Studio command bar in your feature, you will have access to styled shell controls, and you
should not re-template these common controls. However, if you need to build a custom command bar, you might need to
build custom controls as well. In that case, make sure to use the correct token names for each of the following controls so
that your UI is consistent with the rest of Visual Studio.
Search box
Whenever possible, use the common search control provided by the Visual Studio environment. Search box colors are
found in the SearchControl category in the ShellColors.pkgdef file, which contains token names for the input field,
action button, drop-down button, and drop-down menu. A search box can be one of several states, some of which are
mutually exclusive:
Focused or unfocused refers to whether the cursor is in the text box.

Active or inactive refers to whether the user has input a search query in the text box.
Hover means that the user has moused over the search box (this state overrides all other states).
Disabled means that search functionality is turned off for the current context.
Use
when you are designing a custom

search box.
Do not use
State
Component
Focused
Input field
Element
Background
Separator
SearchControl.FocusedBackground
SearchControl.FocusedBorder
SearchControl.FocusedDropDownSeparator
Background
None
Foreground (Text)
Border
Action button
Foreground (Search
glyph)
Foreground (Stop
glyph)
Foreground (Clear
Drop-down button
SearchControl.StopGlyph
SearchControl.ClearGlyph
Border
N/A
Background
SearchControl.FocusedDropDownButton
Foreground (Glyph)
SearchControl.FocusedDropDownButtonGlyph
SearchControl.FocusedDropDownButtonBorder
Background
Active input field
SearchControl.SearchGlyph
glyph)
Border
Unfocused
for anything that is not a search box.

for anything that you do not want to
always match the search box UI.
Foreground (Text)
Border
Separator
SearchControl.SearchActiveBackground
SearchControl.SearchActiveBackground
SearchControl.UnfocusedBorder
SearchControl.DropDownSeparator
State
Component
Unfocused
Inactive input field
Element
Background
SearchControl.Unfocused
SearchControl.Unfocused
Foreground (Text)
Border
Action button
Separator
SearchControl.UnfocusedBorder
Background
N/A
Foreground (Search
SearchControl.SearchGlyph
glyph)
Foreground (Stop
SearchControl.StopGlyph
glyph)
Foreground (Clear
SearchControl.ClearGlyph
glyph)
Drop-down button
Border
N/A
Background
SearchControl.UnfocusedDropDownButton
SearchControl.UnfocusedDropDownButtonGlyp
h
SearchControl.UnfocusedDropDownButtonBord
er
Foreground (Glyph)
Border
Hover
Input field
Action button
Drop-down button
Background
SearchControl.MouseOverBackground
Foreground (Text)
SearchControl.MouseOverBackground
Border
SearchControl.MouseOverBorder
Separator
SearchControl.MouseOverDropDownSeparator
Background
SearchControl.ActionButtonMouseOver
Foreground (Glyph)
SearchControl.ActionButtonMouseOverGlyph
Border
SearchControl.ActionButtonMouseOverBorder
Background
SearchControl.MouseOverDropDownButton
Foreground (Glyph)
SearchControl.MouseOverDropDownButtonGlyp
h
SearchControl.MouseOverDropDownButtonBord
er
Border
Pressed
Action button
Drop-down button
Background
SearchControl.ActionButtonMouseDown
Foreground (Glyph)
SearchControl.ActionButtonMouseOverGlyph
Border
SearchControl.ActionButtonMouseDownBorder
Background
SearchControl.MouseDownDropDownButton
Foreground (Glyph)
SearchControl.MouseDownDropDownButtonGlyp
h
SearchControl.MouseDownDropDownButtonBord
er
Border
Highlighted
(Text only)
Input field
Background
SearchControl.Selection
Foreground (Text)
Border
None
Separator
SearchControl.FocusedDropDownSeparator

State
Component
Disabled
Input field
Action button
Drop-down button
Element
Background
SearchControl.Disabled
Foreground (Text)
SearchControl.Disabled
Border
SearchControl.DisabledBorder
Separator
Background
None
Foreground (Glyph)
SearchControl.ActionButtonDisabledGlyph
Border
None
Background
None
Foreground (Glyph)
SearchControl.DisabledDownButtonGlyph
Border
None
Search drop-down lists

The search box drop-down menu has the potential to be slightly more complex than other drop-down menus in Visual
Studio. The suggested searches and search options sections can appear alone or together in the menu and each one is
colored separately. A line also separates these two sections when they appear together and a border surrounds the entire
drop-down menu.
Use
when you are creating a custom search drop-down
list.
the correct token names for the correct list
components.
Do not use
for drop-down lists that appear in other contexts.

in any background/foreground combination other
than specified.
State
Element
Default
Border
SearchControl.PopupBorder
(No other
Separator
SearchControl.PopupSectionHeaderSeparator
Shadow
states)
State
Component
Default
Suggested searches
Element
Background
SearchControl.PopupItemsListBackgroundGradientBegin
Foreground (Text) SearchControl.PopupItemText

State
Component
Default
Element
Background
SearchControl.PopupSectionBackgroundGradientBegin
Foreground
Search options (check box)
(Check box text)

Foreground
Search options (link)
SearchControl.PopupCheckboxText
(Link text)
SearchControl.PopupButtonText
Header
SearchControl.PopupSectionHeaderGradientBegin
background
Foreground
(Header text)
Hover
Background
SearchControl.PopupSectionHeaderText
SearchControl.PopupControlMouseOverBackgroundGradien
tBegin
Suggested searches
Foreground (Text) SearchControl.PopupMouseOverItemText

Border
SearchControl.PopupControlMouseOverBorder
Background
tBegin
tEnd
Foreground
(Check box text)
Foreground
(Link text)
SearchControl.PopupButtonMouseDownText
Border
SearchControl.PopupControlMouseOverBorder
Check box
SearchControl.PopupControlMouseDownBackgroundGradien
tBegin
SearchControl.PopupControlMouseDownBackgroundGradien
tEnd
Pressed
background
Foreground
(Check box text)
SearchControl.PopupCheckboxMouseDownText
Link background
SearchControl.PopupCheckboxMouseDownText
SearchControl.PopupButtonMouseDownBackgroundGradient
Begin
Foreground (Link
text)
SearchControl.PopupButtonMouseDownText

Hyperlink
The hyperlink is one control that does not have a foreground/background pair. In all cases, use the foreground hyperlink
color, which will appear correctly on dark, gray and white backgrounds. If you do not use the color token for the hyperlink
control, you will see the default system color for pressed, which will flash red. That is the signal that the control is not
using the correct environment color token.
Use
when you need to use a hyperlink.
Do not use
State
Component
Default
Hover
Pressed
Disabled
for anything that is not a hyperlink.
Element
Foreground (Text)
Environment.PanelHyperlink
Foreground (Text)
Environment.PanelHyperlinkHover
Foreground (Text)
Environment.PanelHyperlinkPressed
Foreground (Text)
Environment.PanelHyperlinkDisabled
Infobar
Infobars are used to provide more information about a given context and always appear at the top of a document window
or tool window.
Use
when creating custom infobars.
Do not use
State
Default
Component
for UI elements that are not similar to an infobar.
Element
Background
Foreground (Text)
Environment.InfoBackground
Environment.InfoText
Border

Scrollbar
Scrollbars are styled by the Visual Studio environment, and will not need to be themed. However, you might decide that
you want to leverage the colors used in scrollbars so that your UI always appears consistent with this this part of the Visual
Studio environment.
Use
when you are creating UI that you want to match Visual
Studio scrollbars.
Do not use
State
Component
Default
Scrollbar
Scrollbar arrow
Hover
Scrollbar
Scrollbar arrow
Pressed
Scrollbar
Scrollbar arrow
for anything you don't want to always match scrollbar UI.
Element
Scrollbar
Environment.ScrollBarBackground
Foreground
(Thumb)
Environment.ScrollBarThumbBackground
Background
Environment.ScrollBarArrowBackground
Foreground (Glyph)
Environment.ScrollBarArrowGlyph
Scrollbar
Foreground
Set to same color as scrollbar.
(Thumb)
Environment.ScrollBarThumbMouseOverBackground
Background
Environment.ScrollBarArrowMouseOverBackground
Foreground (Glyph)
Environment.ScrollBarArrowGlyphMouseOver
Scrollbar
Foreground
(Thumb)
Environment.ScrollBarThumbPressedBackground
Background
Environment.ScrollBarArrowPressedBackground
Foreground (Glyph)
Environment.ScrollBarArrowGlyphPressed

Tree view
Several tool windows, including the Solution Explorer,
Server Explorer, and Class View, implement a hierarchical
organizational scheme whose colors are controlled by
color names in the TreeView category. All items in a tree
view have background and text colors. Items that have
nested child elements also have glyphs that indicate
whether the item is expanded or collapsed.
Use
anywhere you need to implement a hierarchical

organizational view.
Do not use
for anything that is not similar to a tree view.

in any background/foreground combination
other than specified.
State
Component
Default
Hover
Drag over
Selected
Focused
Unfocused
Element
Background
TreeView.Background
Foreground (Text)
TreeView.Background
Foreground (Glyph)
TreeView.Glyph
Border
None
Background
TreeView.Background
Foreground (Text)
TreeView.Background
Foreground (Glyph)
TreeView.GlyphMouseOver
Border
None
Background
TreeView.DragOverItem
Foreground (Text)
TreeView.DragOverItem
Foreground (Glyph)
TreeView.DragOverItemGlyph
Border
None
Background
TreeView.SelectedItemActive
Foreground (Text)
Foreground (Glyph)
TreeView.SelectedItemActiveGlyph
Border
TreeView.FocusVisualBorder
Background
TreeView.SelectedItemInactive
Foreground (Text)
Foreground (Glyph)
TreeView.SelectedItemInactiveGlyph
Border
None

State
Component
Hover
over
selected
Focused
Unfocused
Element
Background
Foreground (Text)
Foreground (Glyph)
TreeView.SelectedItemActiveGlyphMouseOver
Border
Background
Foreground (Text)
Foreground (Glyph)
TreeView.SelectedItemActiveGlyphMouseOver
Border
None
Button controls
Use
for buttons in the document well that you want to integrate with
Visual Studio themes (Light, Dark, Blue, or a system High Contrast
theme).
Do not use
State
Default
Disabled
Hover
Pressed
Focused
Component
for buttons that will display against a custom background that is not
part of a Visual Studio theme.
Element
Button
CommonControls.Button
Button border
CommonControls.ButtonBorder
Button
CommonControls.ButtonDisabled
Button border
CommonControls.ButtonBorderDisabled
Button
CommonControls.ButtonHover
Button border
CommonControls.ButtonBorderHover
Button
CommonControls.ButtonPressed
Button border
CommonControls.ButtonBorderPressed
Button
CommonControls.ButtonFocused
Button border
CommonControls.ButtonBorderFocused

Check box controls
Use
for check box controls contained within the document well.
Do not use
for any UI that is not a check box control.
State
Default
Disabled
Hover
Pressed
Focused
Component
Element
Background
CommonControls.CheckBoxBackground
Border
CommonControls.CheckBoxBorder
Text
CommonControls.CheckBoxText
Glyph
CommonControls.CheckBoxGlyph
Background
CommonControls.CheckBoxBackgroundDisabled
Border
CommonControls.CheckBoxBorderDisabled
Text
CommonControls.CheckBoxTextDisabled
Glyph
CommonControls.CheckBoxGlyphDisabled
Background
CommonControls.CheckBoxBackgroundHover
Border
CommonControls.CheckBoxBorderHover
Text
CommonControls.CheckBoxTextHover
Glyph
CommonControls.CheckBoxGlyphHover
Background
CommonControls.CheckBoxBackgroundPressed
Border
CommonControls.CheckBoxBorderPressed
Text
CommonControls.CheckBoxTextPressed
Glyph
CommonControls.CheckBoxGlyphPressed
Background
CommonControls.CheckBoxBackgroundFocused
Border
CommonControls.CheckBoxBorderFocused
Text
CommonControls.CheckBoxTextFocused
Glyph
CommonControls.CheckBoxGlyphFocused

Drop-down/combo box controls
Use
for drop-downs and combo boxes that are part of the document well.
Do not use
for any UI that is not a drop-down or combo box.

for command bar drop-downs or combo boxes.
State
Default
Component
Element
Background
CommonControls.ComboBoxBackground
Border
CommonControls.ComboBoxBorder
Text
CommonControls.ComboBoxText
Separator
CommonControls.ComboBoxSeparator
Glyph
CommonControls.ComboBoxGlyph
Glyph background CommonControls.ComboBoxGlyphBackground

Disabled
Background
CommonControls.ComboBoxBackgroundDisabled
Border
CommonControls.ComboBoxBorderDisabled
Text
CommonControls.ComboBoxTextDisabled
Separator
CommonControls.ComboBoxSeparatorDisabled
Glyph
CommonControls.ComboBoxGlyphDisabled
Glyph background CommonControls.ComboBoxGlyphBackgroundDisabled

Hover
Background
CommonControls.ComboBoxBackgroundHover
Border
CommonControls.ComboBoxBorderHover
Text
CommonControls.ComboBoxTextHover
Separator
CommonControls.ComboBoxSeparatorHover
Glyph
CommonControls.ComboBoxGlyphHover
Glyph background CommonControls.ComboBoxGlyphBackgroundHover

Pressed
Background
CommonControls.ComboBoxBackgroundPressed
Border
CommonControls.ComboBoxBorderPressed
Text
CommonControls.ComboBoxTextPressed
Separator
CommonControls.ComboBoxSeparatorPressed
Glyph
CommonControls.ComboBoxGlyphPressed
Glyph background CommonControls.ComboBoxGlyphBackgroundPressed

State
Component
Focused
Element
Background
CommonControls.ComboBoxBackgroundFocused
Border
CommonControls.ComboBoxBorderFocused
Text
CommonControls.ComboBoxTextFocused
Separator
CommonControls.ComboBoxSeparatorFocused
Glyph
CommonControls.ComboBoxGlyphFocused
Glyph background CommonControls.ComboBoxGlyphBackgroundFocused

Text
input
Highlight
CommonControls.ComboBoxTextInputSelection
selection
Pressed
List
item
Background
view
Border
Item text
Background
shadow
CommonControls.ComboBoxListBackground
CommonControls.ComboBoxListBackgroundHover
CommonControls.ComboBoxListItemBackgroundPress
ed
CommonControls.ComboBoxListItemBackgroundFocus
ed
CommonControls.ComboBoxListBorder
CommonControls.ComboBoxListBorderHover
CommonControls.ComboBoxListBorderPressed
CommonControls.ComboBoxListBorderFocused
CommonControls.ComboBoxListItemText
CommonControls.ComboBoxListItemTextHover
CommonControls.ComboBoxListItemTextPressed
CommonControls.ComboBoxListItemTextFocused
CommonControls.ComboBoxListBackgroundShadow
Tabular data (grid) controls

Tabular data controls, also known as grid controls, are common controls for Visual Studio 2015 that can be used to
present large amounts of data in multiple columns. Standard tabular data controls can be found in multiple places within
Visual Studio 2015: the Error List tool window, IntelliTrace reports, and memory heap view, among others. You should
always use the standard tabular data controls provided by the Visual Studio platform team. However, in some rare
instances, you might not have access to the standard tabular data controls. In these situations, use the following token
names to ensure that your UI is consistent with other tabular data controls in Visual Studio.
Use
Do not use
for tabular or grid controls.
for any UI that is not a tabular or grid control.

Column headers
Column headers consist of a background, a border, the title text, and an optional glyph usually used when a grid is sorted
by that column.
State
Element
Default
Background
Header.Default
Foreground (Text)
Foreground (Glyph)
Environment.CommandBarDragHandle
Border
Header.SeparatorLine
Background
Header.MouseOver
Foreground (Text)
Foreground (Glyph)
Header.MouseOverGlyph
Border
Header.SeparatorLine
Background
CommonControls.CheckBoxBackgroundPressed
Foreground (Text)
CommonControls.CheckBoxBorderPressed
Foreground (Glyph)
CommonControls.CheckBoxTextPressed
Border
CommonControls.CheckBoxGlyphPressed
Hover
Pressed
List view items

List view items consist of a background and the content. The content can be text, an icon, or both.
State
Element
Default
Background
Transparent
Foreground (Text)
Border
None
Background
Foreground (Text)
TreeView.SelectedItemActiveText
Border
None
Background
Foreground (Text)
TreeView.SelectedItemInactiveText
Border
None
Selected (active)
Selected (inactive)

Designer: Manifest Designer

The manifest designer was designed as a way to make it easier to edit the .manifest file in Windows8 and Windows Phone
8 projects. While there is not a shared framework available for consumption it may be appropriate for you to match the
design layout and colors of the orientation/navigation tabs and overall structure. For more information about layout
details see the topic on Spacing guidelines (detailed further in 8: Layout).
Use
for designers that are similar to the Manifest Designer.

in place of using common tab controls at the top of an editor within the document well.
Do not use
if you have more than 6 tabs.

for any UI that is not structured like the Manifest Designer.
State
Default
(selected)
Component
Tab
Description pane
Content page
Element
Background
ManifestDesigner.TabActive
Border
None
Background
ManifestDesigner.DescriptionPane
Background
ManifestDesigner.Background
Dialog helper text
ManifestDesigner.Watermark
Non-selected
Tab
Background
ManifestDesigner.TabInactive
Hover
Tab
Background
ManifestDesigner.TabMouseOver

Tagging
Visual Studio supports tagging, which allows a user to declare searchable keywords for tracking purposes. For example,
project managers and developers can use Team Foundation Server (TFS) to tag work items. The tables below give color
names for both the tag itself and the close icon glyph that appears in hover and selected states. Hex values for TFS
tagging can be found in the Color value reference topic.
Use
for UI that supports tagging.
Do not use
for any other type of UI.
Background
Glyph/Close
Text
Tag
State
Component
Default
Hover
Pressed
Selected
Element
Category.Color name
Background
Tag.Background
Foreground (Text)
Tag.Background
Background
Tag.HoverBackground
Foreground (Text)
Tag.HoverBackgroundText
Background
Tag.PressedBackground
Foreground (Text)
Tag.PressedBackgroundText
Background
Tag.SelectedBackground
Foreground (Text)
Tag.SelectedBackgroundText
Glyph (close icon)

State
Component
Default
Default (tag default)
Hover
Hover (tag default)
Element
Category.Color name
Background
N/A
Foreground (Glyph)
Tag.TagHoverGlyph
Background
Tag.TagHoverGlyphHoverBackground
Foreground (Glyph)
Tag.TagHoverGlyphHover
Border
Tag.TagHoverGlyphHoverBorder

State
Component
Pressed
Pressed (tag default)
Tag selected/
glyph default
Default (tag selected)
Tag selected/
glyph hover
Hover (tag selected)
Tag selected/
glyph pressed
Pressed (tag selected)
Element
Category.Color name
Background
Tag.TagHoverGlyphPressedBackground
Foreground (Glyph)
Tag.TagHoverGlyphPressed
Border
Tag.TagHoverGlyphPressedBorder
Background
N/A
Foreground (Glyph)
Tag.TagSelectedGlyph
Background
Tag.TagSelectedGlyphHoverBackground
Foreground (Glyph)
Tag.TagSelectedGlyphHover
Border
Tag.TagSelectedGlyphHoverBorder
Background
Tag.TagSelectedGlyphPressedBackground
Foreground (Glyph)
(on select AND press)
Border (on select AND
press)
Tag.TagSelectedGlyphPressed
Tag.TagSelecteGlyphPressedBorder

Shell
Background
The environment background consists of two layers. The bottom layer is a solid color that covers the entire integrated
development environment (IDE). The top layer fits under the command shelf and between the tool window auto-hide
channels on the left and right edges of the IDE. As of Visual Studio 2013, the top and bottom background layers are set to
the same color in the light and dark themes.
Use ...
for places that you want to match the
background of the Visual Studio environment.
Do not use ...
as a fill for places that are not background

surfaces.
as a background on which you wish to place
foreground elements.
Component
Element
Category.Color name
Bottom layer
Background
Environment.EnvironmentBackground
Top layer
Background
Environment.EnvironmentBackgroundGradientBegin
Gradient stops set to the

same color value in Visual
Environment.EnvironmentBackgroundGradientEnd
Studio 2013 Light and Dark
Environment.EnvironmentBackgroundGradientMiddle1
themes.
Environment.EnvironmentBackgroundGradientMiddle2

Command shelf
Two sets of token names are used for the command shelf backgrounds: one set for where the menu bar sits and one for
where the command bars sit. An individual command bar group has its own background color values, which are discussed
in more detail in the command bar section.
Use ...
for areas where you place menus or toolbars.

with the correct background/foreground token name combination.
Do not use ...
for areas that are not similar to a command shelf.
State
Element
Category.Color name
Menu bar
Background
Environment.CommandShelfHighlightGradientBegin

Command bar
Environment.CommandShelfHighlightGradientMiddle
Studio 2013.
Environment.CommandShelfHighlightGradientEnd
Background
Environment.CommandShelfBackgroundGradientBegin

Studio 2013.
Environment.CommandShelfBackgroundGradientMiddle
Environment.CommandShelfBackgroundGradientEnd

Toolbox
The toolbox is one of the common tool windows that is most frequently used in Visual Studio. It is essentially a tree
control with a special theme and styling applied.
Use
when you are designing a tool window that you want to always be
consistent with the shell toolbox.
Do not use
State
Component
for anything that is not similar to the toolbox UI, or if you are unsure
whether your UI will have problems if the shell toolbox colors
change.
Element
Default
Category.Color name
Environment.ToolboxContent
Headings
Background
Parent node
Child node
Hover
(Child
node
only)
Selected
Focused parent node
Focused child node
Unfocused parent node
Unfocused child node
OR
Individual items, or entire window if no available controls
Border
None
Foreground
(Glyph)
Environment.ToolboxContent
Foreground (Text) Environment.ToolboxContent

Background
Environment.ToolboxContentMouseOver
Border
None
Foreground (Text)
Environment.ToolboxContentMouseOver
Background
Border
Foreground
(Glyph)
Foreground (Text)
Background
Border
None
Foreground
(Glyph)
Foreground (Text)
Individual items only
Individual items only
From TreeView category


Colors and Styling: Creating new color tokens

IMPORTANT: Before creating new color tokens, check to confirm that there is no shared color that already exists. If
there is a shared color defined for the same type of element and usage, then use the shared color.
Custom color entries are needed for interface elements, such as when you want a color to be specific to an individual
feature or group of features, or when an element does not have colors defined in the current common shared color set.
This article gives you implementation information about how to edit a .pkgdef file using the Visual Studio Theme Editor
tool. The tool allows you to define the color tokens for your UI elements and verify that new color hues will work well
inside Visual Studio.
Package definition files

Package definition (.pkgdef) files are the files that define themes. The colors themselves are stored in theme color .xml
files, which are compiled into a .pkgdef file for a given area. The .pkgdef files are deployed by Visual Studio setup,
processed at runtime, and merged together to define themes.
When you create new color tokens, you might be editing your own category in ShellColors.xml or the theme colors .xml
file used by your feature(s).
If your feature does not have a theme colors .xml file to edit, you will need to create a new empty .xml file, edit it with
ThemeEditor to add new colors, and use CompileColor target in your project file to compile the .xml file into a .pkgdef file.
The .pkgdef file will have to be deployed with your component, so additional setup authoring changes might be required.
The Visual Studio Theme Editor

Start by installing the most current internal Visual Studio Theme Editor. This application should not be confused with the
Visual Studio 2013 Color Theme Editor available from MSDN. Developers can use the tool from MSDN to customize the
color themes Visual Studio uses, but cannot use it to create new color tokens. There are several theme editors available,
and if you have one already installed that wont work with Visual Studio 2013, then you do not have the most current
version.
After installing the Visual Studio Theme Editor, open the theme colors .xml file used by your feature/team, or
ShellColors.xml if you have a category of colors in that environment file. The Visual Studio Theme Editor will open .pkgdef
and .xml files. Visual Studio themes (.vstheme files) should have their extension renamed to .xml to be opened in the
Visual Studio Theme Editor.
Color tokens
A color token is made up of four elements:
Category name: a logical grouping for a set of colors. Use an existing category name if you already have colors
that are specific to your UI element, or group of UI elements.
Token name: a descriptive name for your color token and token sets. Sets include background and foreground
(text) token names as well as all their states, and these should be named so that it is easy to identify the pairs and
the states that they apply to.
Color values (or hues): needed for each colored theme. Always create background and text color values in pairs.
Colors are paired for background/foreground so that the text (foreground) color is always readable against the
background color on which it is drawn. These colors are linked and will be used together in your UI. If the
background is not intended for use with text, you do not need to define a foreground color.
System color name: for use in High Contrast displays.
Example of a pair of color token definitions showing values for three color themes and a High Contrast theme
Creating new color tokens

You can create custom colors using the Visual Studio Theme Editor by following these steps:
1.
2.
3.
4.
5.
Determine the category and token names that you will give your new tokens.
Choose the hues that your UI element will use for each theme and the system color.
Use the theme editor to create your new tokens.
Use the colors in your code.
Test the changes in Visual Studio.
Step 1: Determine your token category and name

The preferred naming scheme for a VSColor is [Category] [UI type] [State]. Do not use the word color in your VSColor
names as it is redundant.
Creating good categories

Category names provide logical groupings, and should be defined as narrowly as possible. For example, the name of a
single tool window could be a category name, but the name of an entire business unit or project team is not. Grouping
entries into categories helps prevent confusion between colors with the same name. In the Shell Colors package definition
file, you will notice that many core shared colors are part of the same category. This is for backwards compatibility reasons
only, and is not considered a best practice.
Naming conventions for token names

A token name must clearly indicate the element type and the situations, or state, at which the color will be applied. For
example, an active data tip's [UI type] could be named "DataTipActive". Since data tips have text, both a foreground and a
background color need to be defined. By using background/foreground pairing, the theme editor will automatically create
the colors "DataTipActive" for the background and "DataTipActiveText" for the foreground.
If the piece of UI has only one state, the [State] part of the name can be omitted. For example, if a search box has a border
and there is no state change that would affect the border's color, then the name for the borders color token can be
merely "SearchBoxBorder."
Some common state names include:
Active
Inactive
MouseOver
MouseDown
Selected
Focused
Examples of a few token names for parts of a list item control:
ListItem
ListItemBorder
ListItemMouseOver

ListItemMouseOverBorder
ListItemSelected
ListItemSelectedBorder
ListItemDisabled
ListItemDisabledBorder
Step 2: Choose appropriate color values

To help choose color values for your themes, refer to Color value reference, which gives examples of existing UI and the
color hues that they use. Because those color sets have already been implemented, you can be reasonably sure that they
will look appropriate and behave correctly in all themes if you use them in a similar way in your own UI.
To help you choose system colors for a High Contrast theme, refer to Choosing High Contrast colors.
Step 3: Create new color tokens in the theme editor

Once you have determined the category, name, and colors for a color entry, map the entry into the Visual Studio Theme
Editor.
Launch the theme editor and open the theme colors .xml file you are using to store your colors.
Add a new color entry

Select New Color from
the toolbar. This opens
a dialog where you can
specify the category and
one or more names for
color entries within that
category:
Select an existing
category or select New
Category to create a
new category. Another
dialog will open and
you can assign your
new category name:
Your category will then become available in the New Color category drop-down menu.

After you have a

category chosen, enter
one or more names for
your new color tokens,
as shown at right:
Once you have created your new color token(s), an entry for each token you entered will appear in the theme editors
color list. Your new token will not have predefined values, so you can then input color values for each theme.
New color tokens showing None before color values have been defined for the themes.
Adding or editing color values

To add or edit a color token, select a color entry for the theme (column) of that token. Add the color value by either typing
a hex color value in 8-digit ARGB format, entering a system color name into the cell, or using the drop-down menu to
select the desired color via a set of color sliders or a list of system colors.
Color value custom color sliders
Color value system colors drop-down selector
For components that do not need to display text, enter only one color value: the background color. Otherwise, enter
values for both background and text color, separated by a forward slash.
When entering values for High Contrast, you must enter valid Windows system color names. Do not enter hardcoded
ARGB values. You can view a list of valid system color names by selecting Background: System or Foreground: System
from the color value drop-down menus. As always, when creating elements that have text components, you must use the
correct background/text system color pair or your text might be unreadable.
Saving your work after adding or changing color values will write the new color entries back to the package definition file.
Step 4: Use the colors in Visual Studio

After defining your new color token, make a reference to it in your project file.
For more information on color tokens, see The VSColor service.
Step 5: Test the changes in Visual Studio

You can use the theme editor to see a temporary view of live changes to colors without rebuilding your package. To see a
temporary view of your changes, click the Apply this theme to running Visual Studio windows button located on the
header of each theme column.
This temporary theme will go away the next time you start Visual Studio.
To make the changes permanent, rebuild and redeploy your Visual Studio package after adding new colors to the package
definition file and writing code that will use those colors. Rebuilding your Visual Studio package will merge the registry
values for your new colors into the rest of the themes. Then relaunch Visual Studio, view your UI, and verify that the new
colors you defined are showing up.

Colors and Styling: Color value reference

This topic is intended for use as a reference for creating new color tokens. You can leverage the work that has been done
for existing UI in designing color choices for all the themes and the system color name for that element.
When using this reference guide, remember:
Always copy both foreground and background hues together. Dont choose a foreground from one UI element
and a background from another just because you like the hues.
You cannot use the actual color token names of these UI elements because you cannot control how they might
be changed in the future, which is why the token names are not listed here. Instead, create tokens within your own
category and use the hue values shown in the tables.
You will get best results if you pair color sets with UI that is similar to the example use.
Color value reference categories

Properties window: Control elements within the Properties Window; Control elements within the Property Grid
CodeLens UI
Grid control
Manifest Designer
TFS tagging
Button controls
Check box controls
Color palettes: Light theme; Dark theme; Blue theme
Visualization surfaces
Charts

Properties window
Here is what the Properties window looks like in all three themes:
Light theme
Dark theme
Blue theme
Control elements within the Properties window

Component
Part
Element
Divider Lines
Expander Glyph
Foreground
Background
Border
Embedded tab
control
Embedded tab
control
Body
Active tab
State
Light
Dark
Blue
High Contrast
Default
FFEEEEF2
FF2D2D30
FFEEEEF2
ControlDark
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Hover
FF007ACC
FF007ACC
FF007ACC
HighlightText
Default
FFF5F5F5
FF252526
FFF6F6F6
Window
Hover
FFC9DEF5
FF3E3E40
FFFFFCF4
Highlight
Default
FFF5F5F5
FF252526
FFF6F6F6
Window
Hover
FFC9DEF5
FF3E3E40
FFE5C365
WindowFrame
Foreground
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Background
Default
FFE7E8EC
FF1B1B1C
FFE7E8EC
Control
Border
Default
FFE7E8EC
FF1B1B1C
FFE7E8EC
WindowFrame
Foreground
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Background
Default
FFE7E8EC
FF1B1B1C
FFE7E8EC
Highlight
Border
Default
FFE7E8EC
FF1B1B1C
FFE7E8EC
WindowFrame
Foreground
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText

Component
Part
Inactive
Element
State
Light
Dark
Blue
High Contrast
Hover
FF1E1E1E
FFF1F1F1
FF1E1E1E
HighlightText
Disabled
FFA2A4A5
FF656565
FFA2A4A5
GrayText
Default
FFF5F5F5
FF252526
FFF6F6F6
Control
Hover
FFC9DEF5
FF3E3E40
FFFEFEFE
Highlight
Disabled
FFF5F5F5
FF252526
FFF6F6F6
Control
Default
FFF5F5F5
FF252526
FFF6F6F6
WindowFrame
Hover
FFC9DEF5
FF3E3E40
FFFEFEFE
WindowFrame
Disabled
FFF5F5F5
FF252526
FFF6F6F6
WindowFrame
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Hover
FF1E1E1E
FFF1F1F1
FF1E1E1E
HighlightText
Default
FFEEEEF2
FF292929
FFEFEFF2
Control
Hover
FFC9DEF5
FF3E3E40
FFFFFCF4
Highlight
Default
None
None
None
None
Hover
FFC9DEF5
FF3E3E40
FFE5C365
WindowFrame
Foreground
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Background
Default
FFF5F5F5
FF252526
FFF6F6F6
Control
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
WindowText
Hover
FF007ACC
FF007ACC
FF007ACC
WindowText
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
WindowText
Hover
FF1E1E1E
FFF1F1F1
FF1E1E1E
HighlightText
Selected
FF1E1E1E
FFF1F1F1
FF1E1E1E
HighlightText
Disabled
FFA2A4A5
FF656565
FFA2A4A5
GrayText
Default
FFF5F5F5
FF252526
FFF6F6F6
Window
Hover
FFC9DEF5
FF3E3E40
FFFFFCF4
Highlight
Selected
FFF5F5F5
FF252526
FFFDF4BF
Highlight
Disabled
FFF5F5F5
FF252526
FFF6F6F6
Window
Default
FFCCCEDB
FF3F3F46
FFCCCEDB
Window
Background
tabs
Border
Section header
Foreground
Background
Border
Category group
Body
Glyph
Foreground
Toggle buttons
Foreground
Background
Border
Input fields
Foreground
Background
Border
List items
Foreground
List items
Background
Hover
FFC9DEF5
FF3E3E40
FFE5C365
WindowFrame
Selected
FF007ACC
FF007ACC
FFE5C365
WindowFrame
Disabled
FFF5F5F5
FF252526
FFF6F6F6
WindowFrame
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Disabled
FFA2A4A5
FF656565
FFA2A4A5
GrayText
FFFFFFFF
FF333337
FFFCFCFC
Control
Disabled
FFF5F5F5
FF252526
FFF6F6F6
Control
Default
FFCCCEDB
FF434346
FFDBDDE6
ControlDark
Disabled
FFCCCEDB
FF434346
FFC6C6C6
ControlDark
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Hover
FF1E1E1E
FFF1F1F1
FF1E1E1E
HighlightText
Selected
FFFFFFFF
FFFFFFFF
FFFFFFFF
HighlightText
Disabled
FFA2A4A5
FF656565
FFA2A4A5
GrayText
Hover
FFC9DEF5
72555555
FFFDF4BF
Highlight
Default

Component
Part
Element
State
Dark
Blue
High Contrast
FF3399FF
FF3399FF
FF3399FF
Highlight
Hover
FFC9DEF5
72555555
FFFDF4BF
WindowFrame
Selected
FFCCCEDB
FF3399FF
FF3399FF
WindowFrame
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
WindowText
Hover
FF1E1E1E
FFF1F1F1
FF1E1E1E
HighlightText
Selected
FFFFFFFF
FFFFFFFF
FFFFFFFF
HighlightText
Disabled
FFA2A4A5
FF656565
FFA2A4A5
GrayText
Selected
Border
Command
buttons
Foreground
Background
Border
Light
Hover
FFC9DEF5
FF3E3E40
FFFEFEFE
Highlight
Pressed
FF007ACC
FF007ACC
FF007ACC
Highlight
Disabled
FFF5F5F5
FF252526
FFF6F6F6
Window
Hover
FFC9DEF5
FF3E3E40
FFFEFEFE
HighlightText
Pressed
FF007ACC
FF007ACC
FF007ACC
HighlightText
Disabled
FFCCCEDB
FF434346
FFC6C6C6
WindowFrame
Control elements within the Properties grid
Light theme
Component
Dark theme
Element
Light
Dark
Blue
High Contrast
Default
FF1E1E1E
FFF1F1F1
FF000000
WindowText
Selected, focused
FFFFFFFF
FFFFFFFF
FFFFFFFF
HighlightText
Selected, unfocused
FF1E1E1E
FFF1F1F1
FF000000
WindowText
Default
FFF5F5F5
FF252526
FFFFFFFF
Control
Selected, focused
FF3399FF
FF3399FF
FF3399FF
Highlight
Selected, unfocused
FFEEEEF2
FF2D2D30
FFEEEEF2
ControlDark
Divider lines
Default
FFEEEEF2
FF2D2D30
FFEEEEF2
ControlDark
Foreground
Default
FF1E1E1E
FFF1F1F1
FF000000
WindowText
Background
Default
FFEEEEF2
FF2D2D30
FFEEEEF2
ControlDark
Content
Foreground
Background
Header
State
Blue theme

CodeLens UI
CodeLens UI colors are the same for Light, Dark, and Blue themes.
Component
Element
State
Body
Foreground
Hyperlink
All themes
High Contrast
Default
FF1E1E1E
WindowText
Foreground
Selected
FFFFFFFF
HighlightText
Background
Default
FFFCFCFC
Window
Background
Selected
FF3399FF
Highlight
Background
Highlighted
FFFDFBAC
HotTrack
Border
Default
FF6DC2E9
WindowFrame
Foreground
Default
FF0E70C0
HotTrack
Default
FF9C9C9C
Separator

Grid control
Light theme
Dark theme
Blue theme
Component
Part
Body
Sub-section
header
Grid lines
Element
State
Light
Dark
Blue
High Contrast
Foreground
Default
FF1E1E1E
FFF1F1F1
FF000000
WindowText
Selected
FFFFFFFF
FFFFFFFF
FFFFFFFF
HighlightText
Foreground
Default
FF717171
FF999999
FF6D6D6D
GrayText
Background
Default
FFF5F5F5
FF252526
FFFFFFFF
Window
Selected
FF3399FF
FF3399FF
FF3399FF
Highlight
Items
Foreground
Default
FFF0F0F0
FF000000
FFF0F0F0
ScrollBar
Header
Foreground
Default
FFE0E3E6
FF333337
FFBEC3CB
ControlDark

Manifest Designer
Light theme
Dark theme
Blue theme
Component
Part
Body
Active tab
Element
State
Light
Dark
Blue
High Contrast
Foreground
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Background
Default
FFF5F5F5
FF252526
FFF6F6F6
Control
Foreground
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ActiveCaptionText
Background
Default
FFF5F5F5
FF252526
FFF6F6F6
ActiveCaption
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
InactiveCaptionText
Hover
FF1E1E1E
FFF1F1F1
FF1E1E1E
InactiveCaption
Default
FFFEFEFE
FF333337
FFFEFEFE
HighlightText
Hover
FFCCCEDB
FF3F3F46
FFCCCEDB
Highlight
Foreground
Default
FF717171
FF999999
FF717171
GrayText
Background
Default
FFF5F5F5
FF252526
FFF6F6F6
Control
Foreground
Default
FF1E1E1E
FFF1F1F1
FF1E1E1E
ControlText
Background
Default
FFFFFFFF
FF252526
FFFFFFFF
Control
Foreground
Inactive tabs
Background
Watermark text
Description
pane

TFS tagging
Light theme
Category.Color name
Dark theme
Blue theme
Light
Dark
Blue
High Contrast
Background
FFE1E6F1/
FF1E1E1E
FF424242/
FFFFFFFF
FFE9ECEE/
FF1E1E1E
Active Caption/
Active Caption Text
HoverBackground
FFC9DEF5
FF606060
FFFDF4BF
Highlight
HoverBackgroundText
FF1E1E1E
FFFFFFFF
FF1E1E1E
Highlight Text
PressedBackground
FF3399FF
FF3399FF
FF3399FF
Highlight
PressedBackgroundText
FFFFFFFF
FFFFFFFF
FFFFFFFF
Highlight Text
SelectedBackground
FF3399FF
FF3399FF
FF3399FF
Highlight
SelectedBackgroundText
FFFFFFFF
FFFFFFFF
FFFFFFFF
Highlight Text
TagHoverGlyph
FF1E1E1E
FFFFFFFF
FF1E1E1E
Highlight Text
TagHoverGlyphHover
FF1E1E1E
FFFFFFFF
FF1E1E1E
Highlight
TagHoverGlyphHoverBackground
FFF7F7F9
FF393939
FFFFFCF4
Highlight Text
TagHoverGlyphHoverBorder
FFF7F7F9
FF393939
FFE5C365
Highlight Text
TagHoverGlyphPressed
FFFFFFFF
FFFFFFFF
FFFFFFFF
Highlight
TagHoverGlyphPressedBackground
FF0E6198
FF007ACC
FFFDF4BF
Highlight Text
TagHoverGlyphPressedBorder
FF0E6198
FF007ACC
FFE5C365
Highlight Text
TagSelectedGlyph
FFFFFFFF
FFFFFFFF
FFFFFFFF
Highlight Text
TagSelectedGlyphHover
FFFFFFFF
FFFFFFFF
FFFFFFFF
Highlight
TagSelectedGlyphHoverBackground
FF52B0EF
FF52B0EF
FF52B0EF
Highlight Text
TagSelectedGlyphHoverBorder
FF52B0EF
FF52B0EF
FF52B0EF
Highlight Text
TagSelectedGlyphPressed
FFFFFFFF
FFFFFFFF
FFFFFFFF
Highlight
TagSelectedGlyphPressedBackground
FF0E6198
FF0E6198
FF0E6198
Highlight Text
TagSelectedGlyphPressedBorder
FF0E6198
FF0E6198
FF0E6198
Highlight Text

Button controls
State
Element
Light
Dark
Blue
High Contrast
Foreground
1E1E1E
F1F1F1
1E1E1E
ControlText
Background
ECECF0
3F3F46
ECECF0
Control
Border
CCCEDB
555555
CCCEDB
ControlDark
Foreground
A2A4A5
656565
A2A4A5
InactivecaptionText
Background
F5F5F5
2D2D30
F5F5F5
Inactivecaption
Border
CCCEDB
3F3F46
CCCEDB
InactiveBorder
Default
Disabled
Hover
Foreground
1E1E1E
F1F1F1
1E1E1E
ActiveCaptionText
Background
C9DEF5
3F3F46
C9DEF5
ActiveCaption
Border
3399FF
007ACC
3399FF
ActiveBorder
Pressed
Foreground
FFFFFF
F1F1F1
FFFFFF
HighlightText
Background
007ACC
007ACC
007ACC
Highlight
Border
007ACC
007ACC
007ACC
HighlightText
Foreground
1E1E1E
F1F1F1
1E1E1E
ActiveCaptionText
Background
C9DEF5
3F3F46
C9DEF5
ActiveCaption
Border
3399FF
007ACC
3399FF
ActiveBorder
Focused

Check box controls

State
Element
Light
Dark
Blue
High Contrast
Background
FEFEFE
252526
FEFEFE
Control
Border
717171
999999
717171
ControlDark
Text
1E1E1E
F1F1F1
1E1E1E
ControlText
Glyph
1E1E1E
F1F1F1
1E1E1E
ControlText
Background
F6F6F6
2D2D30
F6F6F6
InactiveCaption
Border
C6C6C6
434346
C6C6C6
InactiveBorder
Text
A2A4A5
656565
A2A4A5
InactiveCaption
Glyph
A2A4A5
656565
A2A4A5
InactiveCaptionText
Background
F3F9FF
1F1F20
FDF4BF
Highlight
Border
3399FF
007ACC
E5C365
HighlightText
Text
1E1E1E
F1F1F1
1E1E1E
HighlightText
Glyph
1E1E1E
F1F1F1
424242
HighlightText
Background
007ACC
007ACC
E5C365
Highlight
Border
007ACC
007ACC
E5C365
HighlightText
Text
1E1E1E
F1F1F1
1E1E1E
HighlightText
Glyph
FFFFFF
F1F1F1
1E1E1E
HighlightText
Background
F3F9FF
1F1F20
FDF4BF
Highlight
Border
3399FF
007ACC
E5C365
HighlightText
Text
3399FF
F1F1F1
1E1E1E
HighlightText
Glyph
1E1E1E
F1F1F1
424242
HighlightText
Default
Disabled
Hover
Pressed
Focused


Drop-down/combo box
State
Element
Light
Dark
Blue
High Contrast
Background
007ACC
333337
FCFCFC
Control
Border
CCCEDB
434346
8591A2
ControlLight
Text
1E1E1E
F1F1F1
000000
ControlText
Separator
FFFFFFF
333337
FCFCFC
ControlLight
Glyph
717171
999999
1B293E
ControlText
Glyph background
FFFFFF
333337
FCFCFC
Control
Background
EEEEF2
2D2D30
DFE7F3
InactiveCaption
Border
CCCEDB
434346
A4ADBA
InactiveBorder
Text
A2A4A5
656565
A2A4A5
InactiveCaptionText
Separator
EEEEF2
2D2D30
D5DCE8
InactiveBorder
Glyph
CCCEDB
656565
A2A4A5
InactiveCaptionText
Glyph background
EEEEF2
2D2D30
D5DCE8
InactiveCaption
Background
007ACC
3F3F46
FCFCFC
Highlight
Border
007ACC
007ACC
E5C365
HighlightText
Text
1E1E1E
007ACC
000000
HighlightText
Separator
007ACC
007ACC
E5C365
HighlightText
Glyph
1E1E1E
007ACC
000000
HighlightText
Glyph background
C9DEF5
1F1F20
FDF4BF
Highlight
Background
FFFFFF
3F3F46
FCFCFC
Highlight
Border
007ACC
007ACC
E5C365
HighlightText
Text
1E1E1E
FFFFFF
000000
HighlightText
Separator
007ACC
007ACC
E4C365
HighlightText
Glyph
FFFFFF
FFFFFF
000000
HighlightText
Glyph background
007ACC
007ACC
E5C365
Highlight
Background
FFFFFF
3F3F46
FCFCFC
Highlight
Border
007ACC
007ACC
E5C365
HighlightText
Text
1E1E1E
FFFFFF
000000
HighlightText
Separator
007ACC
007ACC
E5C365
HighlightText
Glyph
1E1E1E
007ACC
000000
HighlightText
Glyph background
C9DEF5
3F3F46
FCFCFC
Highlight
Default
Disabled
Hover
Pressed
Focused

Drop-down/combo box list (appears on press)

State
Element
Light
Dark
Blue
High Contrast
Background
F6F6F6
1B1B1C
EFEFEF
Menu
Border
CCCEDB
3F3F46
9BA7B7
MenuText
Text
Default
Hover
1E1E1E
FFFFFF
000000
MenuText
Background
shadow
1900000
1900000
1900000
ControlDark
Background
C9DEF5
3F3F46
FDF4BF
Highlight
Border
C9DEF5
3F3F46
FDF4BF
HighlightText
Text
1E1E1E
FFFFFF
000000
HighlightText
Light
Dark
Blue
High Contrast
66007ACC
66007ACC
66007ACC
HighlightText
Drop-down/combo box text input selection

State
Element
Default
Text input
selection

Color palettes
Light theme
Color (hex)
#FF0E6198
Swatch
Used for
Tool window buttons and selected document window buttons: backgrounds and borders on
mouse down
#FF0E70C0
Hover over auto-hide tab text

Tool window selected tab text
#FF007ACC
Most borders and separators on mouse down and hover

Drop-down button and command bar button backgrounds on mouse down
Focused tool window title bar and document window tab background and border
#FF1C97EA
Background document tabs: background and border on hover

Scrollbar arrow glyphs on hover
#FF3399FF
Selected items: backgrounds and/or borders
#FF52B0EF
Active tool and document window buttons: backgrounds on hover
#FFC9DEF5
Most backgrounds and borders on hover

Search drop-down menu items: background and border on hover, some items on mouse down
#FF442359
Provisional document tab buttons, selected or background: background on mouse down
#FF68217A
VS logo
Active provisional document tab background and border
#FF9B4F96
Selected, focused provisional document tab buttons: background on hover
#FFB064AB
Unselected provisional document tab buttons: background on hover
#FFE51400
Stop, error
#FF1E1E1E
Most text
Drop-down list, combo box, and search control drop-down glyphs on hover
#FF444444
Auto-hide tab text, unfocused tool window title bar text, and tool window tab text
#FF525252
Title bar text for main window and floating document windows
#FF6A6A6A
Scrollbar thumb: background and border on mouse down
#FF717171
Default glyphs
Some instances of unfocused text
#FF888888
Scrollbar thumb: background and border on hover
#FF999999
Drag handles (toolbar and tool window)
#FFA2A4A5
Disabled text
#FFB7B9C5
Selected, unfocused document and provisional tab buttons: background on mouse down
#FFCCCEDB
Default borders and command bar separators

Selected, unfocused tree view background
#FFE0E3E6
Menu bar menu group separators
#FFE6E7ED
Selected, unfocused document and provisional tab buttons: background and border on hover

Color (hex)
Swatch
#FFEEEEF2
Used for
IDE background
Command shelf, menu bar, and command bar backgrounds
#FFF5F5F5
Tool window and scrollbar backgrounds

Dock target button and glyph background and border
#FFF6F6F6
Drop-down list and combo box drop-down menu backgrounds
#FFF7F7F9
Unfocused tool window buttons: background on hover
#FFFFFFFF
Drop-down list, combo box, and unfocused search box selection/input field: default, hover, and
mouse down backgrounds
Combo box and some drop-down list menu items: background on hover and mouse down
Default editor background
Status bar, selected, and active text
Glyphs that appear against dark surfaces
Dark theme
Color (hex)
Swatch
Used for
#FF0E6198
Tool window and selected document window buttons: backgrounds and borders on mouse down
#FF007ACC

Drop-down list, combo box, search control, menu and submenu glyphs on hover
Drop-down button and command bar button backgrounds on mouse down
Focused tool window title bar and document window tab background and border
#FF0097FB
Hover over auto-hide tab text

Tool window selected tab text
#FF1C97EA

Scrollbar arrow glyphs on hover
#FF3399FF
#FF52B0EF
Active tool and document window buttons: backgrounds on hover
#FF55AAFF
Tool window unselected tab text on hover
#FF442359
Provisional document tab buttons, selected or background: background on mouse down
#FF68217A
Active provisional document tab background and border
#FF9B4F96
Selected, focused provisional document tab buttons: background on hover
#FFB064AB
Unselected provisional document tab buttons: background on hover
#FFE51400
Stop, error
#FF1B1B1C
Drop-down list and combo box drop-down menu background

Selected, unfocused document and provisional tab buttons: background on mouse down
Dock target background
#FF1F1F20
Drop-down list and combo box drop-down buttons: background on hover

Focused combo box drop-down button background
#FF222222
Command bar separator

Color (hex)
Swatch
#FF252526
Used for
Tool window backgrounds
Dock target button and glyph background and border
#FF2D2D30
IDE, command shelf, menu bar, and command bar backgrounds
#FF333334
Menu items: background on hover

Drop-down list, combo box, and unfocused search box selection/input field: default background
#FF333337
Separators: menu bar menu group, split button, and search control drop-down menu section
Dock target border
#FF393939
Unfocused tool window buttons: background on hover
#FF3E3E40
Most backgrounds and borders on hover
#FF3E3E42
Scrollbar and scrollbar arrows: default, disabled, hover, and mouse down backgrounds
Drop-down list, combo box, and search control drop-down menu: background on hover and
#FF3F3F46
mouse down
Selected, unfocused tree view background
Default drop-down list and combo box selection/input field border
#FF434346
Drop-down list selection field: border on hover and mouse down

Combo box, drop-down list, search control, and text box: disabled border
Drag handles (toolbar and tool window)
#FF46464A
Command bar separator
#FF555555
Selected, unfocused document and provisional tabs: background and border on hover
#FF656565
Disabled text
#FF686868
Scrollbar thumb: default background and border

Title bar text for main window and floating document windows
#FF999999
Default menu and submenu glyphs
#FF9E9E9E
Scrollbar thumb: background and border on hover
#FFD0D0D0
Auto-hide tab text, unfocused tool window title bar text, and tool window tab text
#FFEFEBEF
Scrollbar thumb: background and border on mouse down

Most text
#FFF1F1F1
Default command bar glyphs

VS logo
Default editor background
#FFFFFFFF
Status bar, selected, and active text

Tool window and document tab buttons: default, hover, and mouse down glyphs
Command bar options: background on hover
#72555555
Search drop-down menu items: background and border on hover and mouse down
Main window and rafted window buttons: background and border on hover
Blue theme
Color (hex)
#FFE5C365
Swatch
Used for
Drop-down buttons: background on mouse down
#FFFFE8A6
Tool window and selected document window buttons: background and border on mouse down
#FFFFF29D
Command bar buttons: background on mouse down

Color (hex)
Swatch
Used for
Tool window title bars and document window tabs: focused background and border
#FFFDF4BF
Command bar buttons, menu items, drop-down buttons, combo box items, and action buttons:
background on hover
Search control drop-down button: focused background
#FFFFFCF4
Selected icons: background on hover

Focused and unfocused tool window and document window buttons: background on hover
#FF0E70C0
Search control "clear" glyph

Drop-down menu link text
#FF007ACC
Default status bar background

Scrollbar arrows: glyph on mouse down
Tree view: default or selected, unfocused glyph on hover
#FF1C97EA
Scrollbar arrows: glyph on hover
#FF3399FF
#FF1B293E
Combo box, drop-down list, menu, and split button: default glyphs
Command bar options: default, hover and mouse down glyph
Menu: mouse down glyph
Command bar text, drop-down and combo box menu item text
#FF293955
IDE and unselected preview tab backgrounds

Auto-hide tab default and hover backgrounds
#FF35496A
IDE background gradient
#FF364E6F
Unselected document window tab background
#FF465A7D
Auto-hide tab border
#FF4B5C74
Tool window unselected tab: separator and default and hover background and border
#FF4D6082
Unfocused document tab, preview tab, and tool window title bar background and border
Title bar drag handle
#FF5B7199
#FF8E9BBC
Tool window border
#FFCFD6E5
Toolbar background
#FFD5DCE8
Combo box, drop-down, and text box disabled backgrounds
#FFD6DBE9
Title bar, menu bar, and command bar backgrounds
#FFDCE0EC
Toolbar options background

Toolbar border
#FFEAF0FF
Default menu background
#FFF2F4FE
Menu icon channel background
#FF000000
Tool window selected tab and command bar: hover, mouse down, and selected text
Document control, drop-down button, and menu glyphs on hover
#FF6A6A6A
Pressed scrollbar thumb
#FF808080
Inactive command bar and menu text
#FF888888
Hover scrollbar thumb

Visualization surfaces
The Visualization Surface Colors represent and differentiate objects on visualization surfaces in Visual Studio. This set is
color-accessible. The three major types of color blindness are accounted for, so users can distinguish objects through
contrast and value.
Each color set consists of a Light, Medium, and Dark value. Gradient fills should use the light and medium values, while
solid fills should use the light value. Dark values should only be used for outlines and borders. The two supplemental
colors can be used to extend the base seven colors when more distinct objects are needed, though there remains a limit of
seven simultaneously displayed colors.
These colors have accessibility conflicts that should be noted:
Steel Blue should not appear with Plum

Red should not appear with Plum, Green, or Brown
Fill colors
Outline/border colors
High Contrast: These colors map to the system color Window
High Contrast: These colors map to the system color WindowText
Hex
RGB
Hex
RGB
Hex
RGB
Hex
RGB
#FFA1C7E7
161,199,231
#FFE2E432
226,228,66
#FF5386BF
83,134,191
#FFCAB22D
202,178,45
#FFB9D4EE
185,212,238
#FFFBF7C8
251,247,200
#FFB8CCD7
184,204,215
#FFA19667
161,150,103
#FF779AB6
119,154,182
#FF705829
112,88,41
#FFC6D4DF
198,212,223
#FFB0A781
176,167,129
#FFCB98B6
203,152,182
#FF8E5478
142,84,120
#FFE2B1CD
226,177,205
Secondary supplemental
Secondary supplemental
colors
colors
Hex
RGB
#FF9FB861
159,184,97
#FF89ABBD
137,171,189
#FFB1C97B
177,201,123
#FFA0B7C7
160,183,201
#FFBFC749
191,199,73
#FFFF7971
255,121,113
#FFD0D4B7
208,212,183
#FFFF9F99
255,159,153
Hex
RGB
#FF5D8039
93,128,57
#FF427094
66,112,148
#FFA79432
167,148,50
#FFAD1C2B
173,28,43

Charts
Charting colors on timeline graph
These colors were designed for use with charts in Visual Studio. The palette is accessible for the major types of color
blindness, and the colors can be differentiated even when used as very narrow slices of color.
You can use these colors in any combination for any type of chart or graph in your UI. You do not need to use all seven
colors if you do not need that many distinct colors. Do not change these colors or introduce new colors without first
talking to a UX designer.
These colors were not designed to be used with any foreground elements, so do not place text or glyphs on top of these
colors without first talking to a UX designer.
Fill colors
Hex
RGB
#71B252
113,178,82
#BF3F00
191,63,0
#FCB714
252,183,20
#903F8B
144,63,139
#117AD1
17,122,209
#79D7F2
121,215,242
#B5B5B5
181,181,181

Colors and Styling: Choosing High Contrast colors

Windows uses several high-contrast systemlevel themes that increase the color contrast of
text, backgrounds, and images, making
elements appear more distinct on the screen.
For accessibility reasons, it is important that
Visual Studio interface elements respond
correctly when users switch to a High Contrast
theme.
Only a handful of system colors can be used for
High Contrast themes. When choosing your
system color names, remember the following
tips:
1.
2.
3.
Choose system colors that have the

same semantic meaning as the element
that you are coloring. For instance, if
you are choosing a high-contrast color
for text within a window, use
WindowText and not ControlText.
Choose foreground/background pairs
together or you will not be confident
that your color choice will work in all
High Contrast themes.
Determine which parts of your UI are
the most important and ensure that
content areas will stand out. You will
lose a lot of detail that subtle
differences in color hue would normally
distinguish, so the use of strong border
colors is common to define content
areas, because there are no color
variants for different content areas.
From the Windows Presentation Foundation Team blog

System color set

The table at right indicates the complete set of system color names, and the corresponding hues displayed in each theme:
When applying this limited set of colors to your UI, it is expected that you will lose subtle details that were present in the
normal themes.
On the following page is an example of UI with subtle gray colors that are used to distinguish areas within a tool window.
When paired with the same window displayed in High Contrast mode, you can see that all the backgrounds are the same
hue and the borders of those areas are indicated by border alone.
Example of how subtle details are lost in High Contrast mode

Choosing text colors in an editor

Colorized text is used in an editor or on a design surface to indicate meaning, such as allowing for easy identification of
groups of similar items. In a High Contrast theme, however, you do not have the ability to differentiate between more than
three text colors. WindowText, GrayText and HotTrackText are the only colors available on WindowBackground surfaces.
Since you cannot use more than three colors, carefully choose the most important differences that you want to display
when in High Contrast mode.
Hues for each of the token names allowed on an editor surface, as they appear in each High Contrast theme
Example of the editor surface in the Blue theme
The same surface in the High Contrast #1 theme

Usage patterns
Many common UI elements already have high-contrast colors defined. You can reference these usage patterns when
choosing your own system color names, so that your UI elements are consistent with similar components.
System color
Usage
ActiveCaption
Active IDE and rafted window button glyphs on hover and press
Title bar background for IDE and rafted windows
Default status bar background
ActiveCaptionText
Active IDE and rafted windows for title bar foreground (text and glyphs)
Background and border of active window buttons on hover and press
Control
Combo box, drop-down list, and search control default and disabled background,
including drop-down button
Dock target button background
Command bar background
Tool window background
ControlDark
IDE background
Menu and command bar separators
Command bar border
Menu shadows
Tool window tab default and hover border and separator
Document well overflow button background
Dock target glyph border
ControlDarkDark
Unfocused, selected document window tab
ControlLight
Auto-hide tab border

Combo box and drop-down list border
Dock target background and border
ControlLightLight
Selected, focused provisional tab border
ControlText
Combo box and drop-down list glyph

Tool window unselected tab text
GrayText
Combo box and drop-down list disabled border, drop-down glyph, text, and menu item
text
Disabled menu text
Search control 'search options' header text
Search control section separator
Highlight
All hover and pressed backgrounds and borders, except combo box drop-down button
background and document well overflow button border
Selected item backgrounds
HighlightText
All hover and pressed foregrounds (text and glyphs)

Focused tool window and document tab window control foreground
Focused tool window title bar border
Focused, selected provisional tab foreground
Document well overflow button border on hover and press
Selected icon border
HotTrack
Scrollbar thumb background and border on press

Scrollbar arrow glyph on press
InactiveCaption
Inactive IDE and rafted window button glyphs on hover

Title bar background for IDE and rafted windows
Disabled search control background

System color
Usage
InactiveCaptionText
Inactive IDE and rafted windows title bar foreground (text and glyphs)
Inactive window buttons background and border on hover
Unfocused tool window button background and border
Disabled search control foreground
Menu
Drop-down menu background

Checked and disabled checkmark background
MenuText
Drop-down menu border

Checkmark check
Menu glyphs
Drop-down menu text
Selected icon border
Scrollbar
Scrollbar and scrollbar arrow background, all states
Window
Auto-hide tab background

Menu bar and command shelf background
Unfocused or unselected document window tab background and document border, for
both open and provisional tabs
Unfocused tool window title bar background
Tool window tab background, both selected and unselected
WindowFrame
IDE border
WindowText
Auto-hide tab foreground

Selected tool window tab foreground
Unfocused document window tab and unfocused or unselected provisional tab
foreground
Tree view default foreground and hover over unselected glyph
Tool window selected tab border
Scrollbar thumb background, border, and glyph

Colors and Styling: Using themed controls

WPF
Most tool windows will be themed automatically through style inheritance from the main and/or floating windows.
Style inheritance works by walking up the parent element chain looking for styles matching the given key. (For styles with
a TargetType, the default key is the type itself.) Most WPF-based tool windows find their ScrollBar/ScrollViewer styles in
the resources of a shell-provided WPF element at the root of the tool window UI hierarchy
(GenericPaneContentPresenter).
For WPF elements for which scrollbar theming doesn't "just work," the preferred way of controlling theming is by use of
the ImageThemingUtilities.ThemeScrollBarsProperty attached property. It controls the theming of scrollbars for
the element it is attached to, as well as any elements contained therein.
From XAML:

< Grid Name="grid1" vs:ImageThemingUtilities.ThemeScrollBars="True">

</Grid>
From code:
// theme the scrollbars all elements within grid1
ImageThemingUtilities.SetThemeScrollBars(grid1, true);
Styles
If you want more control over scrollbar theming (for instance, you want to define your own scrollbar style based on Visual
Studio style), the following Visual Studio-specific scrollbar styles are available in the application's resource dictionary:
Type
Themed style key
Unthemed style key
ScrollBar
VsResourceKeys.ScrollBarStyleKey
VsResourceKeys.UnthemedScrollBarStyleKey
ScrollViewer VsResourceKeys.ScrollViewerStyleKey
GridView
VsResourceKeys.UnthemedScrollViewerStyleKey
VsResourceKeys.CustomGridViewScrollViewerStyleKey VsResourceKeys.UnthemedGridViewScrollViewerStyleKey
Note: The unthemed styles are dynamic resources that could change at runtime if the Windows theme is changed (for
example, from Aero to Windows Classic).

Native
Theming for an HWND is controlled by the value of a particular Windows property (for example, SetProp/GetProp) on the
window:
enum __VSNativeScrollbarThemeMode
{
NSTM_Undefined
= 0, // Theme mode isn't defined yet
NSTM_All
= 1, // Theme all descendants
NSTM_None
= 2, // No theming of descendants
NSTM_OnlyTopLevel = 3, // Theme scrollbars on the window to which this is applied, but not
descendants
};
For controlling this at an IVsWindowFrame level, you can use this window frame property:
VSFPROPID_NativeScrollbarThemeMode = -5026, (I4)
This property uses values from __VSNativeScrollbarThemeMode to indicate whether the native (in this case, Win32)
scrollbars on child windows of this frame should have theming applied.
This property only has an effect on frames whose pane meets one the following criteria:
1.
The pane is created with IVsWindowPane.CreatePaneWindow, or
2.
The pane is created with IVsUIElementPane.CreateUIElementPane and CreateUIElementPane returns

IVsUIWin32Element.
If the frame's pane is created with CreateUIElementPane returning either a FrameworkElement or IVsUIWpfElement and
you wish to control the theming of hosted Win32 scrollbars, you will need to call the Windows ::SetProp function for each
HwndHost you need to control, using the following parameters:
hwnd: HwndHost.Handle
lpString: the string returned by the VSSPROPID_NativeScrollbarThemeModePropName shell property
hData: a value from __VSNativeScrollbarThemeMode, but not NSTM_Undefined
This value is initialized to NSTM_Undefined. Until the time IVsWindowPane.CreatePaneWindow or

IVsUIElementPane.CreateUIElementPane returns, the value can be set to another value from
__VSNativeScrollbarThemeMode, but once set, the value cannot be changed.
If this value is NSTM_Undefined when IVsWindowPane.CreatePaneWindow or IVsUIElementPane.CreateUIElementPane
returns, it will be set to NSTM_All.
For more granular control, anyone (internal or external) can apply the property directly to any HWND. They can find out
the property name by querying for this shell property:
VSSPROPID_NativeScrollbarThemeModePropName = -9071, (BSTR, Read-only.)
The string to be used with ::SetProp/::RemoveProp to control theming of native scrollbars. When calling ::SetProp, the
property value provided should be one of the values in the __VSNativeScrollbarThemeMode enumeration.

HTML (CSS)
Basic scrollbar theming for MSHTML-based web browser components is possible via a set of CSS attributes. As an
example, this matches the Visual Studio Light theme:
body {
scrollbar-3dlight-color: #EFEFEF; /*[{EnvironmentColors.ScrollBarBackgroundColorKey}]*/
scrollbar-darkshadow-color: #EFEFEF; /*[{EnvironmentColors.ScrollBarBackgroundColorKey}]*/
scrollbar-highlight-color: #EFEFEF; /*[{EnvironmentColors.ScrollBarBackgroundColorKey}]*/
scrollbar-shadow-color: #EFEFEF; /*[{EnvironmentColors.ScrollBarBackgroundColorKey}]*/
scrollbar-track-color: #EFEFEF; /*[{EnvironmentColors.ScrollBarBackgroundColorKey}]*/
scrollbar-arrow-color: #606060; /*[{EnvironmentColors.ScrollBarArrowGlyphColorKey}]*/
scrollbar-face-color: #CCCCCC; /*[{EnvironmentColors.ScrollBarThumbBackgroundColorKey}]*/
scrollbar-base-color: red; /*IE no longer uses this property */
}
This styling is restricted to color and is based on legacy schemes. By default, the scrollbars will use styling to match the OS,
so Windows 8 would get Modern-themed scrollbars and Windows 7 would get classic scrollbars. Also note that there is no
distinct color for the arrow glyph background: it uses the scrollbar face on Windows 7 and the track color on Windows 8.
In order to dynamically update these colors, you can subscribe to the Visual Studio theme change event and update the
relevant property values.

Colors and Styling: Exposing colors for end users

Sometimes you will want to allow the end user to customize your UI, such as when you are creating a code editor or
design surface. The most common way to do this is by using the Tools > Options dialog. Unless you have highly
specialized UI that requires special controls, the easiest way to present the customization is through the Fonts and Colors
page within the Environment section of the dialog. For each element that you expose for customization, the user can
choose to change the foreground color, background color, or both.
Building a VSPackage for your customizable colors

A VSPackage can control the fonts and colors through custom categories and display items on the Fonts and Colors
property page. When using this mechanism, VSPackages must implement the IVsFontAndColorDefaultsProvider interface
and its associated interfaces.
In principle, this mechanism can be used to modify all existing display items and the categories that contain them.
However, it should not be used to modify the Text Editor category or its display items. For more information on the Text
Editor category, see Font and Color Overview.
To implement custom categories or display Items, a VSPackage must:
Create or identify categories in the registry. The IDE's implementation of the Fonts and Colors property page
uses this information to correctly query for the service supporting a given category.
Create or identify groups in the registry (optional). It might be useful to define a group, which represents the
union of two or more categories. If a group is defined, the IDE automatically merges subcategories and distributes
display items within the group.
Implement IDE support.
Handle font and color changes.
For more detailed information, see the MSDN article Accessing Stored Font and Color Settings.
To create or identify categories

Construct a special type of category registry entry under [HKLM\SOFTWARE\Microsoft \Visual Studio\<Visual Studio
version>\FontAndColors\<Category>]. <Category> is the non-localized name of the Category.
Populate the registry with two values:
Name
Type
Data
Description
Category
REG_SZ
GUID
A GUID created to identify the category
Package
REG_SZ
GUID
The GUID of the VSPackage service that supports the category
The service specified in the registry must provide an implementation of IVsFontAndColorDefaults for the corresponding
category.

To create or identify groups

Construct a special type of category registry entry under [HKLM\SOFTWARE\Microsoft \Visual Studio\<Visual Studio
version>\FontAndColors\<group>]. <group> is the non-localized name of the group.
Populate the registry with two values:
Name
Type
Data
Description
Category
REG_SZ
GUID
A GUID created to identify the group
Package
REG_SZ
GUID
The GUID of the service that supports the category
The service specified in the registry must provide an implementation of

T:Microsoft.VisualStudio.Shell.Interop.IVsFontAndColorGroup for the corresponding group.
To implement IDE support

Implement GetObject, which returns either an IVsFontAndColorDefaults interface or an
T:Microsoft.VisualStudio.Shell.Interop.IVsFontAndColorGroup interface to the IDE for each category or group GUID
supplied. For every category it supports, a VSPackage implements a separate instance of the IVsFontAndColorDefaults
interface. The methods implemented through IVsFontAndColorDefaults must provide the IDE with:
Lists of display items in the category

Localizable names for display items
Display information for each member of the category
Note: Every category must contain at least one display item.

The IDE uses the T:Microsoft.VisualStudio.Shell.Interop.IVsFontAndColorGroup interface to define a union of several
categories.
Its implementation provides the IDE with:
A list of the Categories that make up a given group

Access to instances of IVsFontAndColorDefaults supporting each Category within the group
Localizable group names
Updating the IDE

The IDE caches information about Font and Color settings. Therefore, after any modification of the IDE Font and Color
configuration, ensuring that the cache is up to date is a best practice.
Updating the cache is done through the IvsFontAndColorCacheManager interface and can be performed globally or just
on selected items.

Handling font and color changes

To properly support the colorization of text that a VSPackage displays, the colorization service supporting the VSPackage
must respond to the user-initiated changes made through the Fonts and Colors properties page.
To do this, a VSPackage must:
handle IDE-generated events by implementing the IVsFontAndColorEvents interface. The IDE calls the
appropriate method following user modifications of the Fonts and Colors page. For example, it calls the
OnFontChanged method if a new font is selected.
OR
poll the IDE for changes. This can be done through the system-implemented IVsFontAndColorStorage interface.
Although primarily for support of persistence, the GetItem method can obtain font and color information for
Display Items. For more information on font and color settings, see the MSDN article Accessing Stored Font and
Color Settings.
Note: To ensure that polling results are correct, use the IVsFontAndColorCacheManager interface to determine if a cache
flush and update are needed prior to calling the retrieval methods of the IVsFontAndColorStorage interface.
Registering custom font and color Category without implementing interfaces

The following code sample demonstrates how to register the custom font and color Category without implementing
interfaces:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp\FontAndColors\CSharp Tool Window]
"Package"="{F5E7E71D-1401-11D1-883B-0000F87579D2}"
"Category"="{9FF46859-A47E-47bf-8AC5-EC3DBE69D1FE}"
"ToolWindowPackage"="{7259e420-6241-4e0d-b535-5b820671d183}"
"NameID"=dword:00000064
Note:
NameID = the resource ID of the localized category name in your package.

ToolWindowPackage = Package GUID.
"Category"="{9FF46859-A47E-47bf-8AC5-EC3DBE69D1FE}" is just an example and the actual value can be a new
GUID provided by the implementer.

Set the font and color property Category GUID

The code sample below demonstrates how to set Category GUIDs:
// m_pView is your IVsTextView
IVsTextEditorPropertyCategoryContainer spPropCatContainer =
(IVsTextEditorPropertyCategoryContainer)m_pView;
if (spPropCatContainer != null)
{
IVsTextEditorPropertyContainer spPropContainer;
Guid GUID_EditPropCategory_View_MasterSettings =
new Guid("{D1756E7C-B7FD-49a8-B48E-87B14A55655A}");
hr = spPropCatContainer.GetPropertyCategory(
ref GUID_EditPropCategory_View_MasterSettings,
out spPropContainer);
if(hr == 0)
{
hr =
spPropContainer.SetProperty(
VSEDITPROPID.VSEDITPROPID_ViewGeneral_FontCategory,
catGUID);
hr =
spPropContainer.SetProperty(
VSEDITPROPID.VSEDITPROPID_ViewGeneral_ColorCategory,
catGUID);
}
}

Colors and Styling: Daytona and web UI

Daytona is a set of APIs, tools, and services that enable a user to create plugins with HTML, CSS, and JavaScript that can
be used in a variety of hosts, such as Visual Studio or F12. Plugins are composed of a portable component, which is written
in HTML, CSS and JavaScript, and optional host-specific components. Each Daytona host can have its own set of UI
conventions, either implicit or explicit, that a plugin must conform to in order to appear native to its environment. Some
hosts, such as Visual Studio, allow end users to make changes to the default theme so that the hosts visual aspects
cannot be statically targeted when authoring a style sheet. This poses a challenge to developers building portable plugins.
This topic explains how to author web UI in Visual Studio using the Daytona host in a way that properly supports both
theming and High Contrast.
Daytona theming mechanism

The Daytona runtime provides a set of services that abstracts the UI conventions and theming capabilities of the host.
These services ensure that plugins automatically conform to the visual expectations of the user based on the environment
they are hosted in. This behavior is provided by three primary features:
1.
A runtime-injected style sheet (plugin.css) that transparently applies a set of CSS rules to a plugins UI and styles
the default set of HTML controls (for example, HTMLInputElement and HTMLButtonElement)
2.
A set of host-provided tokens that can be used to style UI elements using values that are theme-based instead of
hardcoded
a.
a declarative syntax for accessing these tokens with CSS
b. an API for programmatically accessing theme tokens from JavaScript

3.
Notification of theme changes
Runtime-injected style sheet

The Daytona runtime coordinates with the host to inject a style sheet that automatically themes the standard UI elements
of a plugin. This includes styling for the following concepts:
Environment font
Background colors
Hyperlinks
Form controls (for example: <select>, <input>, <button>)
Tables
Headings
Scrollbars
This means that if your UI is composed entirely of standard HTML UI controls, then no additional work should be needed
to respond correctly to theme changes and to support High Contrast.
Custom UI
In almost every nontrivial case, the standard HTML UI controls will be insufficient for providing a complete experience for a
plugin and custom UI must be introduced. In order to support proper font choice and color use, theme tokens should be
used either declaratively in CSS or imperatively via the JavaScript API described below. The Daytona runtime will take care
of updating the style sheets that use these tokens on plugin load and on theme changes.
Theme tokens
Both standard and host-specific theme tokens are available. Standard tokens are host-injected and always available. Using
the standard tokens wherever possible is preferable. Standard tokens are guaranteed to be provided by all Daytona hosts,
and using them makes your plugin inherently more portable. The set of standard tokens is subject to change, though only
new tokens should be added and none should be removed. The Visual Studio 2013 version is documented below:
Token name
Description
plugin-background-color
The default background color for the plugin
plugin-color
The default foreground color for the plugin
plugin-contextmenu-active-color
The default foreground selection color for active context menus
plugin-contextmenu-background-color
The default background color for context menus
plugin-contextmenu-border-color
The default border color for context menus
plugin-contextmenu-color
The default foreground color for context menus
plugin-contextmenu-hover-color
The default hover background color for context menus
plugin-contextmenu-hover-text-color
The default hover foreground color for context menus
plugin-contextmenu-icon-checkbox
The default check box icon color for context menus
plugin-contextmenu-inactive-text-color
The default foreground selection color for inactive context menus
plugin-contextmenu-separator-color
The default separator color for context menus
plugin-font-family
The default font family to use for the plugin.
In Visual Studio, the following plugin-font tokens are based on the Environment font settings:
plugin-font-size
plugin-font-weight
plugin-highlight-background-color
plugin-highlight-color
plugin-inactive-color
The following plugin-link tokens are used to style HTMLLinkElements (hyperlinks):
plugin-link-color
plugin-link-active-color
plugin-link-hover-color
Plugin.css styles scrollbars by default using the following tokens to better support the themes in the various hosts (in
particular, Visual Studio):
plugin-scrollbar-arrow-color
plugin-scrollbar-background-color
plugin-scrollbar-face-color
The following plugin-select tokens are used to style the HTMLSelectElement (combo box/drop-down):
plugin-select-option-background-color
plugin-select-option-color
plugin-select-option-checked-background-color
plugin-select-option-checked-border-color
plugin-select-option-checked-foreground-color
plugin-select-option-hover-background-color
plugin-select-option-hover-border-color
plugin-select-option-hover-foreground-color
plugin-select-border-color
plugin-select-background-color
plugin-select-foreground-color
plugin-select-hover-background-color
plugin-select-hover-border-color
plugin-select-hover-foreground-color
plugin-table-border-color
plugin-table-header-background-color
plugin-table-header-color
plugin-textbox-border-color
plugin-textbox-background-color
plugin-textbox-color
plugin-textbox-disabled-background-color
plugin-textbox-disabled-border-color
plugin-textbox-disabled-color

These tokens should be used for all tree views and tables, because they have the correct defaults set in the various hosts
to support themes and High Contrast:
plugin-treeview-content-background-color
plugin-treeview-content-color
plugin-treeview-content-inactive-selected-color
plugin-treeview-content-mouseover-background-color
plugin-treeview-content-mouseover-color
plugin-treeview-content-inactive-selected-color
plugin-treeview-content-selected-background-color
plugin-treeview-content-selected-border-color
plugin-treeview-content-selected-color
Host-specific tokens
In addition to supporting the standard set of tokens, hosts may also provide nonstandard tokens. The Visual Studio host
does this by allowing the plugin to specify theme token aliases in a Visual Studio-specific section of the manifest. For
example:
"vs": {
"theme_token_aliases": {
"diagnostics-host-border": {
"category": "f8a8b2a5-dd35-43f6-a382-fd6a61325c22",
"key_type": "BackgroundColor",
"name": "Border"
},
...
}
}
This example introduces a theme token, named diagnostics-host-border, which can be referenced identically to the
standard tokens mentioned above. The category, key_type, and name are used to resolve the color through the
IVsFontAndColorStorage interface. In many cases, its possible to find appropriate colors (along with the category,
key_type, and name information) in the XML files located in vscommon\themes. This same mechanism is used if your
package introduces new configurable colors: match the category, key_type, and name to the color that youd like to use.
Plugin authors should attempt to use standard tokens whenever possible and only use host-specific tokens when
absolutely necessary.
Using theme tokens in CSS

Theme tokens are referred to via a specifically formatted comment syntax. The rules for token parsing:
1.
The comment expression must be enclosed within square brackets ([ ]).
2.
All whitespace within the comment, but outside of the expression, is ignored.
3.
The comment expression must directly follow the property it replaces.
4.
Any leading or trailing whitespace within the expression will be trimmed.
5.
Each token name within the expression must be enclosed in curly braces (for example, {font-family} and {buttonhover-color}). Otherwise, it will be treated as a literal value.
The following page lists examples of how the token parser will replace CSS values, assuming that the plugin-backgroundcolor token has the value of #000 and the plugin-font-family token has the value of Verdana.

Authored CSS
Parsed CSS
Notes
background-color: #fff;
background-color: #000;
/*[{plugin-background-color}]*/
The default value is replaced with the

dynamic host-specific value.
/*
[{plugin-backgroundcolor}]
*/
/*[
{plugin-backgroundcolor}
]*/
/*{plugin-background-color}*/
The whitespace outside of the

expression is ignored.
The trailing and leading whitespace

within the expression is trimmed.
The expression isn't enclosed in square

brackets, and therefore the comment
is ignored.
/*[plugin-background-color]*/
background-color: pluginbackground-color;
The token isn't enclosed in curly

braces, and is therefore treated as a
literal value.
/*[{plugin-background-color}]*/ background-color: #fff;

The comment doesn't follow the

property value and is therefore
ignored.
font-family: Arial, sans-serif;
/*[{plugin-font-family}, sansserif]*/
background-image: lineargradient(0% #000, 100% #ccc);
/*[linear-gradient(0% #000,
100% {plugin-backgroundcolor})]*/
Same as above
Same as above
font-family: Verdana, sansserif;
The token is replaced and the literal

content is maintained.
background-image: lineargradient(0% #000, 100% #000);
Same as above
If a CSS file includes theme tokens, it must be marked by the data-plugin-theme attribute on the link element in the HTML
file. For example:
<link href="default.css" rel="stylesheet" data-plugin-theme="true" />

Using theme tokens from JavaScript

While custom UI should be themed by CSS where possible, there are scenarios when the value of a theme token needs to
be accessed programmatically. For example, if custom UI is being drawn onto a CanvasElement that doesnt inherit styling
from CSS, or if a UI element is being dynamically created as opposed to referencing style sheets. The scenarios are
enabled by using the Daytona API Plugin.Theme.getValue. This function returns a host-provided theme value when given
a token name.
Not themed
Themed
var surface =
document.getElementById("surface").getContext("
2d");
surface.fillStyle = "#ccc";
surface.fillRect(0, 0, 200, 200);
var surface =
document.getElementById("surface").getContext("
2d");
surface.fillStyle = ("plugin-backgroundcolor");
surface.fillRect(0, 0, 200, 200);
var el = document.createElement("div");
el.style.backgroundColor = "#ccc";
var el = document.createElement("div");
el.style.backgroundColor =
Plugin.Theme.getValue("plugin-backgroundcolor");
If tokens are used from JavaScript, the theme change event must be handled to respond to updates. This is unnecessary
for theme tokens used declaratively in CSS, as the Daytona runtime takes care of it for the plugin. The theme event can be
handled in the following way:
Member (single handler)
DOM-Event (multiple handlers)
Plugin.Theme.onchange = function () {
// re-draw dynamic UI here
}
Plugin.Theme.addEventListener("change",
function () {
// re-draw dynamic UI here
});
In this case, it would be common to re-call Plugin.Theme.getValue in these handlers, as the value of the theme tokens
likely changed when the theme changed.

Standard token mapping

The standard tokens are mapped to Environment and Shell colors. The list below gives a flavor of what those mappings
are, but this list is incomplete. To see the most up-to-date list of standard tokens and mappings, browse to
bptoob\ScriptedHost\Library\ThemeHelper.cs and look at the RefreshTokenMap method.
Token name
VS mapping (EnvironmentColors)
plugin-color
plugin-link-color
plugin-link-hover-color
ToolWindowTextColorKey
ToolWindowBackgroundColorKey
ControlLinkTextColorKey
ControlLinkTextHoverColorKey
plugin-link-active-color
plugin-highlight-color
plugin-highlight-background-color
plugin-table-header-background-color
plugin-table-header-color
plugin-table-border-color
ControlLinkTextPressedColorKey
HighlightTextColorKey
HighlightColorKey
GridHeadingBackgroundColorKey
GridHeadingTextColorKey
GridLineColorKey
plugin-button-background-color
plugin-button-hover-background-color
plugin-button-color
plugin-button-border-color
plugin-color
ButtonFaceColorKey
ButtonHighlightColorKey
ButtonTextColorKey
ButtonBorderColorKey
ToolWindowTextColorKey
ToolWindowBackgroundColorKey

Theme changes
The Visual Studio host triggers plugin theme changes when an end user makes changes to the following settings:
Color theme
Environment theme
OS theme (only when changing to and from High Contrast)

4: Images and Icons

2015 RC PREVIEW
Images and Icons: Image use in Visual Studio

Before creating artwork, consider making use of the 1,000+ images in the Visual Studio Image Library.
Types of images
Images used in the Visual Studio user interface generally belong to one of several major categories:
Icons. Small images that appear in commands, hierarchies, templates, and so on. The default icon size used in
Visual Studio is a 16x16 PNG. Icons produced by the image service automatically generate the XAML format for
HDPI support.
NOTE: While images are used in the menu system, you should not create an icon for every command. See
Command usage to see whether your command should get an icon.
Dialog images. Images that appear in dialogs or wizards, either as descriptive graphics or message indicators. Use
infrequently and only when necessary to illustrate a difficult concept or gain the user's attention (alert, warning).
Animated images. Used in progress indicators, status bars, and operation dialogs.
Cursors. Used to indicate whether an operation is allowed using the mouse, where an object may be dropped, and
so on.
Illustrative (nonfunctional) and decorative imagery. Most often branded material.
114 Visual Studio UX Guidelines: Images and Icons

EARLY PARTNER PREVIEW OF 2015 GUIDELINES. SUBJECT TO CHANGE. FOR QUESTIONS OR FEEDB ACK, EMAIL UXBOARD@MICROSOFT.COM.
Images and Icons: Visual Language Dictionary

Visual Studio uses a common visual language to illustrate the concepts that are the building blocks of its iconography and
other imagery. When designing new icons, use this dictionary to identify the concepts that you want to convey in your
own image. This is about the concept, not the visual representation.
General guidelines:
These visual concepts must be used consistently with their dictionary definition. Otherwise, you risk confusing
your users, who expect common elements to have consistent meanings.
Choose only the most relevant or important concepts for use in your icons, so that the imagery is crisp and easy
to distinguish.
Use only one or two concepts in each image.
For more strategies for designing icons, see Icon design.
Skip to section:
Concepts
Products and platforms
Common concepts using arrows
Status indicators
Concepts
Concept
Icon and examples
Accessibility
Action
Activity
Note: this icon can also be used

as an annotation to indicate that
the base action will be performed
using automatic settings.
Action log
Code activity
Actor
Add behavior
Add
Add all driver tests

Add attachment
Address
Visual Studio UX Guidelines: Images and Icons 115

Alert
Alpha channel
Animation
Animation error
Next animation
Application
Project
Area
Application role error

C++ MFC project
Spline area chart
Stacked area series
Arrange
Arrange shapes
Auto-arrange shapes
Assign
Association
Add association
Edit association
Note: this concept is represented
by the juxtaposition of opposite
imagery (for example, light/dark
or left/right).
Asymmetric
Attach
Add attachment
Open attachment
Attribute
Variable, parameter
Account attribute
Add parameter
Member variable

Audio playback
Audio
Sound file
Audio mute
Audio recording
Record screen and voice

Record mute
Autosum
Bidirectional
Binary
Launch instrumentation target binary
Bookmark project
Bookmark
Clear bookmark
Go to previous bookmark
Branch
Branch uploaded
Remote branch
Brightness
Brightness down
Brightness up
Browse
Browse next
Browse previous
Bug
Create new bug

Edit bug

Private build instance

Build
User-created build
Build selection
Builder
Cube builder
Dimension builder
Online business
Business
Business objects data source

Business model template
Image button
Button
Add button
Linked button
Cache
Cache OK
Cache refresh
Calendar
Date/time axis
Global calendar
Call browser
Call
Call browser settings

Caller or callee view
Cancel
Cancel build
Note: the same icon is used for

"Clear" and "Delete."

Capture frame
Capture
Full screenshot
Start capturing graphic diagnostics
CD
CD drive
Certificate
Certificate error
Certificate warning
Changeset
Group changesets
New changeset
Choice toggle
Checkbox field column

Checkbox list
Class
Add class
Class details tool window
Clear bookmark
Clear
Clear all breakpoints

"Cancel" and "Delete."
Clear collection
Close
Terminate
Close results
Close all
Terminate process
Cloud
Cloud package
Cloud service

Code
Coded UI test
Convert to coded web test
Collapse
Return to collapsed value

Collapse all
Collection
Clear collection
Count collection
Autosize column
Column
Column details
Column error
Comment
Feedback, annotation
Add comment
Callout
Comment (code)
Uncomment
Compare folders
Compare
Compare data
Compare performance reports
Add component
Component
Phone Windows RT component

Component diagram
Add connection
Connect
Connect test plan

Connect to environment
Console
Console test

Contract (noun)
Contract error
Contract warning
Note: used to indicate an

agreement between the
application and the operating
system.
Note: used in layout situations to

indicate that space between two
elements will be condensed.
Contract/expand
Contrast
Add control
Control
Add custom control

Add inherited control
Convert branch to folder
Convert
Convert partition
Convert to coded web text
Copy
Copy aggregation
Copy website
Note: duplicating and stacking

the object represents the copy
action.
Counter
Create new variable

Create
Create new bug

Create new graph
Cursor
Pointer
Set hotspot tool

Inspect mode button

Custom expression
Prediction
Data mining prediction
Cut
Dark theme
Dark theme on
Compare both databases

Data
Database audit specification

Database project
Data mining prediction
Data mining
Data mining structure

Data mining column
Delegate
Invoke delegate
Delete dataset
Delete
Delete folder

"Cancel" and "Clear."
Delete column
Dependency
Deploy
Deployment configurations
Deployment configuration extensions
Diagram
Workflow
New diagram
Show diagram pane

Dialog
Dialog test group

Test dialog
Add new dictionary

Dictionary
Add to dictionary
Clear dictionary
Dimension
Plan
Dimension builder view

Dimension translation view
Dimension browser view
Display
Monitor
Document
File
Display configurations
Full screenshot
Documents library
Format document
File download
Drive
Floppy drive
CD drive
Driver test group explorer
Driver
Network NDIS driver template

Driver package template
ASP.NET dynamic control
Dynamic
Dynamic validator
C# dynamic data website
Edit query
Edit
Address editor
Edit relation
Note: the edit annotation faces

left or right depending on what
the base icon looks like. Choose
the orientation that looks best
with your overall icon design.

Note: The same icon is also used

for Function and Variable.
Effects
C++ empty project

Empty
F# empty website project

Blank page
Enumerator
Create enumerator
Connect to environment
Environment
Create library environment

Library environment
Event
Trigger
Expand
Add event
Event log
Return value expanded
Export filter
Export
Export report data

Export report filter
Favorite
Protected, rating
Field
Add to favorites
Rating
Edit field
Add field
Field (code element)
Go to field
New field
Auto filter
Filter
Chart filter
Export filter

Finance
Money editor
Flag thread flagged

Flagged
Flag thread not flagged

Show only flagged threads
Flow
Documents library
Folder
Find in files
Folder open
Linked folder open
Font color
Font
Font size
Serif
Frame
Friend
Function
Expression
Function warning
WPF page function
Get
Download
Get dictionary value

Get item from collection
Download folder
Graph
Bar chart
HPC performance session wizard

Graphics (3-D)
Asset data grid control

Grid
Grid app C++

Toggle grid
Grid web layout
Grid element
Grid splitter element
Dialog group
Grouping
Team
Virtual machines
Hierarchy
Note: stacking multiple objects

on top of each other represents
the concept of grouping or
multiplicity.
Hierarchy variable
Call hierarchy
History
Home
LightSwitch home screen
Idea
Image
Assets, resource
Image loader
Image button
Image list control
Important
Attention, hot path
Indexer
Show hot lines

Hotspot
Add indexer

Add inherited control

Inheritance
Add inherited form

Inherited control
Note: This concept of inheritance

represents a toolbox control for
a modeling service.
Inheritance
Interface
Note: The concept of derived

inheritance is represented by a
dotted corner. See also
Nonsubstantive/hidden and
Virtual.
Implement interface
Copy item
Item
Create list item

Check in item
Key
Permission, ID
New key
Permission
Get current item ID
Key performance indicator

(KPI)
Delete KPI
KPI browser view
KPI with error
C++ class library project
Library
Exports library
F# Windows Forms control library
Convert to hyperlink
Link
Create linked table

Edit link
Lock
Private, permission
Lock X axis
Branch permissions
Private queue
Log
Plan, catalog
Catalog properties
Action log
Connect test plan

Loop
Add or insert conditional loop

Conditional loop
Mail
Message
Message queue
Message received trace
Email address viewer
Edit manifest
Manifest
Extension manager manifest

New application manifest
Markup error
Markup tag
Markup
Tag or event snippet
Note: the markup concept is also

used as an element in several
compound concepts.
Match tag
Edit tag
Markup: HTML (web)
HTML file
WPF application
Markup: XAML (WPF)
WPF browser application VB

WPF control library
Markup: XML
Reload XML
XML file
Master page
Measure
File from new master
Measure calculated
Measure expression
Media
Film
My movie collection

Member
Material editor, specular
for 3D
Add member
Member calculated
Member variable
Memory configuration
Memory (chip)
Memory array
Page file
Memory
Memory tool window
Automerge all
Merge
Merge changes with tool

Merge module reference
Message
Chat
Extract method
Method
Invoke method
Cube builder view
Mobile services
Mobile phone
Mobile game components

VB mobile web project
Merge module project
Module
Add module
Merge module exclude
Move
Remove using namespace

Namespace
Sort using namespace

Add using namespace
Network
Connection
Network driver package template

Connection offline
Connection unknown
Node
Crosshair
Nonsubstantive (hidden or
template)
Same as Virtual
Hidden field
Hidden folder
Note: A dotted outline of an

object indicates that it is hidden
or templated.
Dynamic template
Note
Open attachment
Open
Open comparison result

Open file dialog
Output
Cloud package
Package
Create package
Driver package template
Parallel
Parallel for each
Partition scheme
Partition
New partition
Partition function
Parts
Assigned part
Misassigned part
Performance
Pin
Unpin, hide
Unpin
Note: The Planning icon is used
to indicate part of a workflow on
a design surface.
Planning
Policy
Visual Studio policy cache

Visual Studio policy description language
Pop out
Power
Previous
Pop in
Uninterruptible power supply
Previous bookmark
Find previous
Print direct
Print
Print dialog
Print document control
Procedure
Interactive window
Interactive window
Procedure warning
Stored procedure
Property
Settings, configurations
Add property
Extended property - warning
New property
Edit query
Query
Query extender
Quick query
Record
Record screen
Go to recorded test session

Redo
Broken reference
Reference
Go to reference
Refresh
Refresh cloud service

Cache refreshing
Relationship
Branch
Define relationship
Add relationship
Parent-child
Remote
Remote branch
Remote desktop
Remove
Rename
Reorder
Reorder parameters
Repair
Report
Upgrade report
File dialog report

Instrumentation performance report
Report project wizard
New extraction rule
Rule
New threshold rule

New validation rule

Ruler
Measure, guide
Measure mode on
Units of measure
Save all
Save
Save and close

Save file dialog control
Create schema
Schema
Database schema
XML schema
Script
Export to script
Generate change script
Search
Find, lookup
Find in files
Find results
Add SQL server
Server (local)
Login server role

Configure computers
Server (remote)
Add server
Run server tests
Services
Legacy only
Computer services
Add web service
WCF workflow service
Settings
Services, process
Call browser settings

Prepare process failed
Test settings
Share
Shortcut

Snippet
Snippet checked
Tag or event snippet
Source control
Start
Run
Change source control
Run concurrency profiling

Server started
Start graphic diagnostics
Steps
Stage, phase
Create shared steps

Insert shared steps
Play all steps
Struct (structure)
Style sheet
New style sheet

Attach style sheet
Synchronize
Update
Updated JavaScript
Database updated items
Sync
Table warning
Table
Cloud storage table collection

Add table
Tablet
Tablet settings
Tablet warning
Tag
Tagging system
Task
Linked task
Task list

New team project

Team
Add team project

Team Foundation Server
Add all driver tests
Test
All loaded tests

Assign tester to test
Picture and text
Text
Rich text box

Text first indent on
Many threads stopped
Thread
Hide all except selected threads

Hide selected threads
Time
Pending
Timer
Time up or down
Time picker on
Time finish
Time start
Toggle
Toggle all breakpoints

Toggle
Toolbox
Winform toolbox control

WPF toolbox control
Undo
Revert, restore
Up
Upload
User
Role, profile
Image restore
Undo check out item
File upload parameter
One level up
Add user
Add web user control
SQL user-defined type
User interface
UI
New variable
Variable (local)
Local variable
SQL variable
Variable properties
Variable (global)
Global variable
Delete variable
View
Advanced view
Data source view
View
Audit
Resource view
View in browser
X-ray view
Virtual
Same as Nonsubstantive
(hidden or template)
Visible
Watch
Virtual environment
Cloak or hide
File system watcher

Publish to web
Web
Download web settings

New website
Map layer wizard
Wizard
MFC class wizard

Map wizard
Work item
Go to work item
Work item query

Yield
Zoom in
Zoom
Zoom out
Products and platforms

Product/Platform
Icon and examples
App Insights
ATL active server page component

ATL
ATL control class

ATL server
Blend SketchFlow application
Blend
Blend Windows Phone application

Blend Windows Phone pivot application
CoffeeScript
Crystal reports
Crystal reports
Github
LightSwitch
C# LightSwitch extension library
Mercury
Microsoft Foundation Class

(MFC)
MFC ActiveX control project

MFC application project
C++ MFC DLL project

Visual Studio
Visual Studio (transparent

logo)
Feedback tool
Visual Studio solution file (11)

Visual Studio solution file (12)
Visual Studio settings
Visual Studio Blend
Visual Studio Express for

Web

Windows

Win 8

Windows Phone
Visual Studio Online
Visual Studio for Windows

Desktop
WCF data services

WCF
WCF project F#
WCF project VB
WF project C#
WF
WF project VB

Common concepts using arrows

Arrow
Icon and examples
Association line
Branch
Camera orbit
Connector
Current context
Current location
Current row
Cursor
Delegation tool
Dependency
Direct selection

Down
Download
Download web settings

Download folder
Sort ascending
ASP.NET dynamic control
Dynamic
Dynamic validator
C# dynamic data website
Expand
Export filter
Export
Export report filter (data)

Export report filter
(Glyph) up
(Glyph) down
(Glyph) next
(Glyph) previous
(Glyph) collapsed file picker
(Glyph) expanded file

picker
Import
Import catalog part

Import filter

Inheritance
Current pointer
Instruction pointer
Historical pointer
Call return pointer
Automerge all
Merge
Merge changes with tool

Move to bottom
Move to top
Navigate back
Navigate forward
Next
Generate, go to
Hyperlink back
Hyperlink forward
Next error
Generate table
Go to source code
Open attachment
Open
Open comparison result

Open file dialog
Previous
Previous bookmark
Find previous
Redo

Reorder
Reorder parameters
Sync
Sync contents
Undo
Revert, restore
Image restore
Up
Upload
File upload parameter
Uncomment
One level up
Status indicators
Status
Icon and examples
Action status: paused
Action status: playing,

running
Action status: stopped
Alert
Server paused
Server started
Never run
Server stopped
Linked table with error tab cue

Code analysis window
Breakpoint: advanced
disabled
Breakpoint: advanced
enabled
Breakpoint: bound

Breakpoint: disabled
Breakpoints window
Breakpoint: enabled
Clear all breakpoints

Toggle all breakpoints
Breakpoint: mapped
disabled
Breakpoint: mapped enabled
Task complete
Complete and OK
Process done
Cloud service OK
Critical
Error
Breakpoint error
Certificate error
Check constraint error
Critical
Offline
Connection offline
Folder offline
Stop query
Help/inconclusive
Compiled MS help file

MS help index file
Information
Rigid info relationship

System info
Information tooltip

Invalid
No
Microphone mute
Mute, not applicable
Required
Audio mute
Test suite requirement
Security shield alert
Security shield complete and

OK
Security shield critical
TracePoint: advanced
disabled
TracePoint: advanced
enabled
TracePoint: disabled
TracePoint with error

TracePoint with warning
TracePoint: enabled
TracePoint: bound
Missing application role

Warning
Assembly not found

Key not found

Images and Icons: Icon design

Visual Studio uses modern-style icons, which have clean geometry and a 50/50 balance of positive/negative (light/dark),
and use direct, understandable metaphors. Crucial icon design points center around clarity, simplification, and context.
Clarity: focus on the core metaphor that gives an icon its meaning and individuality.
Simplification: reduce the icon to its core meaning--get the theme across with just the necessary element(s) and
no frills.
Context: consider all aspects of an icon's role during concept development, which is crucial when deciding which
elements constitute the icon's core metaphor.
With icons, there are a number of design points to avoid:
Don't use icons that signify UI elements except when appropriate. Choose a more abstract or symbolic approach
when the UI element is neither common, evident, nor unique.
Don't overuse common elements like documents, folders, arrows, and the magnifying glass. Use such elements
only when essential to the icon's meaning. For example, the right-facing magnifying glass should indicate only
Search, Browse, and Find.
Although some legacy icon elements maintain the use of perspective, don't create new icons with perspective
unless the element lacks clarity without it.
Don't cram too much information into an icon. An icon cannot tell the whole story.
Icon creation
Concept development
Visual Studio has within its UI a wide variety of icon types. Carefully consider the icon type during development. Don't use
unclear or uncommon UI objects for your icon elements. Opt for the symbolic in these cases, such as with the Smart Tag
icon. Note that the meaning of the abstract tag on the left is more obvious than the vague, UI-based version on the right:
Correct
Incorrect
There are instances in which standard, easily recognizable UI elements do work well for icons. Add Window is one such
example:
Correct
Incorrect
Don't use a document as a base element unless it is essential to the icon's meaning. Without the document element on
Add Document (below) the meaning is lost, whereas with Refresh the document element is unnecessary to communicate
the meaning.

Correct
Incorrect
The concept of "show" should be represented by the icon which best illustrates what is being shown, such as with the
Show All Files example. A lens metaphor may be used to indicate the concept of "view" if necessary, such as with the
Resource View example.
Show
View
Show All files
Resource View
The right-facing magnifying glass icon should represent only Search, Find, and Browse. The left-facing variant with the
plus sign or minus sign should represent only zoom in/zoom out.
Search
Zoom
In tree views, do not use both the folder icon and a modifier. When available, use only the modifier.
Correct
Incorrect

Style details
Layout
Stack elements as shown for standard 16x16 icons:
Status notification elements are better used as standalone icons. There are contexts, however, in which a notification
should be stacked on the base element, such as with the Task Complete icon:
Standalone notification icons
Task Complete icon

Project icons are typically .ico files that contain multiple sizes. Most 16x16 icons contain the same elements. The 32x32
versions have more details, including the project type when applicable.
VB Windows Control Library Project icons, 16x16 and 32x32
Center an icon within its pixel frame. If that is not possible, align the icon to the top and/or right of the frame.
Icon centered within the pixel frame
Icon aligned to the top right of the frame
Icon centered and aligned to the top of the frame

To achieve ideal alignment and balance, avoid obstructing the icon's base element with action glyphs. Place the glyph near
the top left of the base element. When adding an additional element, consider the alignment and balance of the icon.
Correct
Incorrect
Ensure size parity for icons that share elements and are used in sets. Note that in the incorrect pairing, the circle and arrow
are oversized and don't match.
Correct
Incorrect
Use consistent line and visual weights. Evaluate how the icon you are building compares to other icons by using a side-byside comparison. Never use the entire 16x16 frame, use 15x15 or smaller. The negative-to-positive (dark-to-light) ratio
should be 50/50.
Correct
Incorrect
Use simple, comparable shapes and complementary angles to build your elements without sacrificing element integrity.
Use 45 or 90 angles where possible.

Perspective
Keep the icon clear and understandable. Use perspective and a light source only when necessary. Although using
perspective on icon elements should be avoided, some elements are unrecognizable without it. In such cases, a stylized
perspective communicates the element's clarity.
3-point perspective
1-point perspective
Most elements should be facing or angled to the right.
Use light sources only when adding necessary clarity to an object.

Correct
Incorrect
Use outlines only to enhance legibility or to better communicate the metaphor. The negative-positive (dark-light) balance
should be 50/50.
Correct
Incorrect

Icon types
Shell and command bar icons consist of no more than three of the following elements: one base, one modifier, one
action, or one status.
Examples:
Tool window command bar icons consist of no more than three of the following elements: one base, one modifier, one
Examples:
Tree view disambiguator icons consist of no more than three of the following elements: one base, one modifier, one
Examples:
State-based value taxonomy icons exist in the following states: active, active disabled, and inactive disabled.
Examples:
IntelliSense icons consist of no more than three of the following elements: one base, one modifier, and one status.
Examples:

Small (16x16) project icons should have no more than two elements: one base and one modifier.
Examples:
Large (32x32) project icons consist of no more than four of the following elements: one base, one to two modifiers, and
one language overlay.
Examples:
Production details
All new UI elements should be created using Windows Presentation Foundation (WPF) and all new icons for WPF should
be in 32-bit PNG format. The 24-bit PNG is a legacy format that does not support transparency and is therefore not
recommended for icons.
Save the resolution at 96 DPI.
File types
32-bit PNG: the preferred format for icons. A lossless data compression file format that can store a single raster
(pixel) image. 32-bit PNG files support alpha-channel transparency, gamma correction, and interlacing.
32-bit BMP: for non-WPF controls. Also called XP or high color, 32-bit BMP is an RGB/A image format, a truecolor image with an alpha-channel transparency. The alpha channel is a layer of transparency designated in Adobe
Photoshop that is then saved within the bitmap as an additional (fourth) color channel. A black background is
added during artwork production to all 32-bit BMP files to provide a quick visual cue about the color depth. This
black background represents the area to be masked out in the UI.
32-bit ICO: for Project icons and Add Item. All ICO files are 32-bit true color with alpha-channel transparency
(RGB/A). Because ICO files can store multiple sizes and color depths, Vista icons are often in an ICO format
containing 16x16, 32x32, 48x48, and 256x256 image sizes. In order to display properly in Windows Explorer, ICO
files must be saved-down to 24-bit and 8-bit color depths for each image size.
XAML: for design surfaces and Windows adorners. XAML icons are vector-based image files that support scaling,
rotating, filing, and transparency. They are not common in Visual Studio today but are becoming more popular
because of their flexibility.
SVG
24-bit BMP: for the Visual Studio command bar. A true-color RGB image format, 24-bit BMP is an icon
convention that creates a layer of transparency by using magenta (R=255, G=0, B=255) as a color key for a knockout transparency layer. In a 24-bit BMP, all magenta surfaces are displayed using the background color.
24-bit GIF: for the Visual Studio command bar. A true-color RGB image format that supports transparency. GIF
files are often used in Wizard artwork and GIF animations.

Icon construction
The smallest icon size in Visual Studio is 16x16. The largest in common use is 32x32. Keep in mind not to fill up the entire
16x16, 24x24, or 32x32 frame when designing an icon. Legible, uniform icon construction is essential to user recognition.
Adhere to the following points when building icons.
Icons should be clear, understandable, and consistent.

It is better to use the status notification elements as single icons and not to stack them on top of an icon base
element. In certain contexts, the UI might require the status element to be paired with a base element.
Project icons are usually .ico files that contain several sizes. Only the 16x16, 24x24, and 32x32 icons are being
updated. Most 16x16 and 24x24 icons will contain the same elements. The 32x32 icons contain more details,
including the project language type when applicable.
For 32x32 icons, the base elements generally have a 2-pixel line weight. A 1- or 2-pixel line weight can be used for
detail elements. Use your best judgment to determine which is more suitable.
Have at least a 1-pixel spacing between elements for 16x16 and 24x24 icons. For 32x32 icons, use 2-pixel spacing
between elements and between the modifier and base element.
Element spacing for icons sized 16x16, 24x24, and 32x32, respectively:
Color and accessibility

Visual Studio compliance guidelines require that all icons in the product pass the accessibility requirements for color and
contrast. This is achieved through icon inversion, and when you are designing, you should be aware they will be inverted
programmatically in the product.
For more information on using color in VS icons, see Using Color In Images.

Images and Icons: Using color in images

Icons in Visual Studio are primarily monochromatic. Color is reserved to convey specific information and never for
decoration. Color is used:
to indicate an action
to alert the user to a status notification
to designate language affiliation
to differentiate items within IntelliSense
This article will help you understand the different ways in which colors may be used and the corresponding color palettes
for each situation. It will also introduce you to the accessibility guidelines related to color and contrast.
Accessibility
Visual Studio compliance guidelines require that all icons checked into the product pass the accessibility requirements for
color and contrast. Colors in the visual language palette have been tested and meet these requirements.
Color inversion for dark themes

In order to make icons appear with the correct contrast ratio in the Visual
Studio 2013 dark theme, an inversion is applied programmatically. The colors
in this guide have been chosen in part so that they invert correctly. Restrict
your use of color to this palette, or you will get unpredictable results when
the inversion is applied.
In certain scenarios, it is possible to opt out of the icon inversion. For more
information about when and how to do this, see Icon design.
Examples of icons with their colors inverted
Base palette
All standard icons contain three base colors. Icons contain no gradients or drop shadows, with one or two exceptions for
3D-tool icons.
Usage
Name
Value (light theme)
Background/Dark
VS BG
424242 / 66,66,66
Foreground/Light
VS FG
F0EFF1 / 240,239,241
Outline
VS Out
F6F6F6 / 246,246,246
Swatch
Example
In addition to the base colors, each icon may contain one additional color from the extended palette.

Extended palette
Action modifiers
The four colors below indicate the types of actions required by action modifiers:
Usage
Name
Value (all themes)
Positive
VS Action Green
388A34 / 56,138,52
Negative
VS Action Red
A1260D / 161,38,13
Neutral
VS Action Blue
00539C / 0,83,156
Create/New
VS Action Orange
C27D1A / 194,156,26
Swatch
Examples
Green is used for positive action modifiers such as Add, Run, Play, and Validate.
Red is used for negative action modifiers such as Delete, Stop, Cancel, and Close.
Blue is applied to neutral action modifiers most commonly represented as arrows, such as Open, Next, Previous,
Import, and Export.
Dark gold is primarily used for the New modifier.
Special cases
In special cases, a colored action modifier may be used independently as a standalone icon. The color used for the icon
reflects the actions that the icon is associated with. This use is limited to a small subset of icons, including:

Code hierarchy palette

Folder
Folder icons are a pale gold color. Folder icons are the only icons that use this color, which does not invert and looks
correct in all themes.
Usage
Name
Value (all themes)
Swatch
Folders
Folder
DCB67A / 220,182,122
Example
Visual Studio languages

Each of the common languages or platforms available in Visual Studio has an associated color. These colors are used on
the base icon, or on language modifiers that appear in the upper right corner of compound icons.
Usage
Name
Value (all themes)
ASP, HTML, WPF
ASP HTML WPF Blue
0095D7 / 0,149,215
C++
CPP Purple
9B4F96 / 155,79,150
C#
CS Green (VS Action Green)
388A34 / 56,138,52
CSS
CSS Red
BD1E2D / 189,30,45
F#
FS Purple
672878 / 103,40,120
JavaScript
JS Orange
F16421 / 241,100,33
VB
VB Blue (VS Action Blue)
00539C / 0,83,156
TypeScript
TS Orange
E04C06 / 224,76,6
Python
PY Green
879636 / 135,150,54
Swatch
Examples of icons with language modifiers

IntelliSense
IntelliSense icons use an exclusive color palette. These colors are used to help users quickly distinguish between the
different items in the IntelliSense popup list.
Usage
Name
Value (all themes)
Class, Event
VS Action Orange
C27D1A / 194,125,26
Extension Method, Method, Module,
VS Action Purple
652D90 / 101,45,144
Delegate
Field, Enum Item, Macro, Structure, Union
VS Action Blue
00539C / 0,83,156
Value Type, Operator, Interface

Object
VS Action Green
Constant, Exception, Enum Item, Map, Map
Background (VS BG)
Swatch
388A34 / 56,138,52
Item, Namespace, Template, Type
424242 / 66,66,66
Definition
Examples
CLASS
PRIVATE
DELEGATE
EVENT
METHOD
FIELD
FRIEND
ENU
OBJECT
TEMPLATE
ITEM
EXCEPTION
SHORTCUT
Notifications
Notifications in Visual Studio are used to indicate status. The notification palette uses the following four colors, as well as
black or white foreground fill options, to define notifications with the following status levels.
Usage
Name
Value (all themes)
Status: neutral
Notification Blue (VS Blue)
1BA1E2 / 27,161,226
Status: positive
Notification Green (VS Green)
339933 / 51,153,51
Status: negative
Notification Red (VS Red)
E51400 / 229,20,0
Status: warning
Notification Yellow (VS Orange)
FFCC00 / 255,204,0
Foreground fill
Notification Black (Black)
000000 / 0,0,0
Foreground fill
Notification White (White)
FFFFFF / 255,255,255
Swatch
Examples

Images and Icons: Icon theming and inversion

General implementation approach
Find the place closest to the rendering of icons to perform the inversion. To perform the inversion correctly, the code
doing the inversion must know the background the icon is going to be drawn on, so performing the inversion in a data
model level will general not work unless the data model is aware of the UI the image will eventually be drawn on.
Cache inverted images and only regenerate the inverted image if the background or source image changes.
Dont use temporary background color as the source color for inversion. For example, if the selection color in a TreeViewbased window is drawn behind the icon, do not have a special case for inverting the icon differently when selected. Always
use the permanent background to avoid cases where icons invert in unusual ways during selection
New public native APIs

IVsUIShell5.ThemeDIBits
This API takes an array of BGRA32-format pixels as input and applies in-place inversion.
IVsUIShell5.CreateThemedImageList
This API creates a new HIMAGELIST that is a copy of a source HIMAGELIST, with every icon in the image list inverted. The
caller is responsible for destroying the new HIMAGELIST. The new HIMAGELIST will not be updated if images are added to
the original imagelist. Its the callers responsibility to call the method again if the source HIMAGELIST changes.
WPF helpers
ImageThemingUtilities.GetOrCreateThemedBitmapSource
This API gets an already-created themed bitmap from an original source bitmap, or creates a new themed bitmap and
caches the value. The caching mechanism uses a ConditionalWeakTable to attach the inverted image to the original image.
The ConditionalWeakTable will hold the inverted image in memory as long as the original image exists, or until the theme
changes.
ImageThemingUtilities.ImageBackgroundColor
Use the ImageThemingUtilities.ImageBackgroundColor attached property to store the source background Color. This
allows you to bind a Color to the actual Brush used for the background, and allows that Color to inherit down to the actual
image elements where images are drawn.
ThemedImageSourceConverter
This converter takes as input an ImageSource representing the image to be inverted, a Color representing the background,
and a bool indicating whether or not the image should be drawn enabled or disabled. For images that are always enabled,
true can be passed always. The output image is inverted based on the background color and grayscaled if isEnabled is
false.
This converter works the same way as ThemedImageSourceConverter, but the output is an Image control and not an
ImageSource.

5: Menus and Commands

2015 RC PREVIEW
Menus and Commands: Command usage

Unlike Microsoft Office, which is a suite that comprises many separate products, Visual Studio contains many products that
each contribute their command sets to the global Visual Studio IDE. The IDE manages the complexity of thousands of
commands by filtering the functionality available to the user based on context.
When a user's context changes such as switching from a design window to a code editing window functionality
unrelated to the new context disappears. At the same time, new functionality surfaces together with related dynamic
information, such as Properties and Toolbox options. The user should not notice the swapping of the available command
set. If the user is distracted or confused by commands appearing or disappearing, then the UI design needs adjustment.
The user's current context is always indicated in one or more ways, such as in the IDE title bar, the Properties window, or
the Property Pages dialog box.
Command bars allow for flexibility in the UI. The only command structures inherent to the Visual Studio environment are
the main menu and the main command bar, which can both be customized and even hidden. Other command bars appear
and disappear based on the state of the application. Tool windows and document editors can also contain embedded
toolbars within their window edges.
Basic guidelines
Use existing shared commands, command groups, and menus whenever possible.
Since commands are typically shown based on context, use of existing shared menus and command groups ensures that
the command structure remains relatively stable between changes in context. Reusing shared commands and placing new
commands close to related shared commands also reduces IDE complexity and creates a more user-friendly experience.
Reuse shared controls whenever possible. If a new command needs to be defined, try to place it in an existing shared
command group. If a new group needs to be defined, place it in an existing shared menu close to a related command
group before creating a new top-level menu.
Do not create icons for every command.

Think carefully before you create a command icon. Icons should be created only for commands that:
Appear on a default toolbar
Are likely to be added by users to a toolbar through the Customize dialog
Have an icon associated with the same action in another Microsoft product.
Limit the addition of keyboard shortcuts.

The vast majority of users employ a tiny fraction of all available shortcuts. When in doubt, don't bind your feature to a
keyboard shortcut. Work with your user experience team before adding new shortcuts.
Give commands a default menu placement.

Be aware that your commands will be customized by others and design them accordingly. There is no such thing as a
hidden command. All Visual Studio commands appear in the Tools > Customize dialog, the Command Window, autocomplete, the Tools > Options > Keyboard dialog, and the Development Tools Environment (DTE). Make sure to give your
commands a name and tooltip in your .ctc file so that users can find them easily.
Do not duplicate shared commands on an embedded toolbar.

It is useful to place commands in close proximity to the area of the users focus. One way to do this is to create an
embedded toolbar at the top of your tool window or document editor. The commands placed on the toolbar should be
160 Visual Studio UX Guidelines: Menus and Commands
specific to the content region within the window. Do not duplicate shared commands on these toolbars. For example,
never place a Save icon within an embedded toolbar.
Content and command visibility

Commands exist in the following scopes: Environment, Hierarchy, and Document. Know each scope in order to have
confidence in command placement.
Commands in the Environment scope establish primary context and are shared between multiple contexts. They alter the
visibility or arrangement of documents and tool windows. Among the commands in the environment scope are New
Project, Connect to Server, Attach Process, Cut, Copy, Paste, Find, Options, Customize, New Window, and View Help.
Commands in the Hierarchy scope manage hierarchies in Visual Studio including Project, Team, and Data. They relate to a
project's subcontext for example, Debug, Built, Test, Architecture, or Analyze. Among the commands in the Hierarchy
scope are Add New Item, New Query, Project Settings, Add New Data Source, Launch Performance Wizard, and New
Diagram.
Commands in the Document scope act on the contents of a document, such as code, design, or a work item query (WIQ).
They also act on the view of a tool window or are otherwise specific to that tool window. Document scope commands also
act on the file objects that are themselves hierarchy-specific, such as Remove from Project. Among the commands in the
document scope are Refactor > Rename, Create Copy of Work Item, Expand All, Collapse All, and Create User Task.
Command placement decisions

Once you've decided to create a command, you'll need to determine its appropriate placement and whether to create a
keyboard shortcut. Follow this decision path to establish where to place the command:
Visual Studio UX Guidelines: Menus and Commands 161

Command placement in menus

Main menu bar
The main menu bar should be the standard location for commands of any context-specific menu packages that contribute
to the UI. The main menu bar differs from other command structures in that the environment uses it to control which
commands are visible. All other command bars simply disable commands that are out of context, whether they are placed
on a menu or on a toolbar.
The environment defines a set of commands built into the main menu bar that are common across the entire IDE and
multiple task domains. These commands are always visible regardless of which VSPackages are loaded into the
environment. Although VSPackages can extend this set of commands, the command set from each product and the
placement of their commands is the responsibility of each team.
The structure of the Visual Studio main menu can be broken down into the following menu categories:
Core menus
Project-specific menus
Context-specific menus
Document-specific menus
File
Project
Team
Format
Edit
Build
Data
Table
View
Debug
Test
Tools
Architecture
Window
Analyze
Help
When designing main menus, adhere to these rules:
Do not exceed 25 top-level items in a given context.
Menus should never exceed 600 pixels in height.
Evaluate a main menu in multiple contexts, such as in the Ultimate SKU and the General Profile.
Flyout menus are acceptable.
Flyout menus should contain at least three items and no more than seven.
Flyout menus should go only one level deep some Visual Studio menu items have cascading submenus, but this
pattern is not encouraged.
Use no more than six separators. Groupings should adhere to the following illustration:
While it is not required to have each grouping in the figure, adding additional groupings is restricted.
Each grouping should have from two to seven menu items.

Main menu ordering

Before adding a new top-level item, consider placing the command in an existing top-level menu. When adding a new
top-level menu, be sure to place it in the correct location. Decide whether the menu is specific to project, context, or
document. Keep the name of the top-level menu concise and use only one word.
The core menus should bookend the rest of the commands. File, Edit, and View should always be to the left, and Tools,
Window, and Help should always be to the right.
Context menus
Placing too much functionality within the context menus results in a difficult-to-learn interface. All major functionality
should be available through the main menu bar. Placement of commands should be reconciled with existing commands to
avoid duplicate commands. For context menus, the shell defines standard menu groups that should be included
depending on whether the context menu is for the solution, a project node, or a project item.
When designing context menus, adhere to the same rules as for the main menu, and in addition:
Do not exceed 25 top-level menu items. Five of these placements are reserved for partner teams, so DevDiv teams
should limit context menus to 20 items. When evaluating a context menu, be sure to review it in the Ultimate SKU
in a variety of differing contexts.
Flyout menus are acceptable but must not exceed one level deep never use cascading flyouts.
Use no more than six separators.
Command placement in toolbars

General toolbars
When designing and arranging toolbars, follow these standards:
Don't use more than one verb per button. One button
= one action.
Use text alongside the icon only if it needs to be

reinforced with the label.
Use a combo box exclusively for properties that will be

switched multiple times in one session. Otherwise,
expose the property elsewhere.
The width of a combo box should equal the width of

the longest item within the box + 30%. For instance, if
the longest item is 200 pixels, then the combo box
should be 260 pixels wide.
Limit the use of separators. The use of a separator next

to a dropdown is an anti-pattern, because the shape of
the dropdown itself acts as a visual separator.
Example of a split button. The six commands on the left can

instead fit into a single button.
Icon groups should contain from three to six icons.
If qualifiers result in multiple useful commands, use a split button that stores the last setting, as shown above.
Product-specific toolbars
Each product can provide a default toolbar that contains frequently used and important commands, and each product's
default toolbar should appear the first time Visual Studio is started after the product is installed.

Products should also leverage shared command groups and menus provided by the IDE. Each shared command group is
placed in a shared menu meant to organize related commands in a meaningful way for the user. It is important to leverage
this shared command structure in order to reduce complexity.
Global toolbars
Global toolbars are required to fit on one row right out of the box. When creating a new global toolbar, follow the
guidelines for that toolbar type.
General toolbar guidelines:
Each toolbar has 24 pixels in common controls (gripper, overflow).
Each toolbar button is 22 pixels wide including padding. Making the icon a split button adds another 11 pixels of
width.
Duplication of commands across toolbars is allowed.
Document-specific toolbars appear when a certain file type is active and disappear when a different file type becomes
active.
Document-specific toolbars may not have more than 12 buttons.
The total width of the toolbar may not exceed 300 pixels.
Each file type can have either one embedded toolbar or one document-specific global toolbar, but not both.
Context-specific toolbars appear when a certain context is set and tend to stay active for extended periods.
The button limit for all context-specific toolbars is 18.
If most users won't consistently employ this toolbar's commands when the context is active, then don't associate
this toolbar with a context.
Ensure that the toolbar disappears when exiting context. None of these toolbars should appear on startup.
Toolbars with no context never appear automatically. These show only when the user activates them. Keep the maximum
width below 200 pixels.
General organization and shell-defined groups

Use existing shared commands, command groups, and menus. If a
new command needs to be defined, try to place it in an existing
shared command group. If a new group needs to be defined, try to
place it in an existing shared menu close to a related command
group before creating a new top-level menu. This reduces
command complexity while ensuring consistent command
placement in the IDE.
The shared Format menu, typically shown in the context of
designer-style document windows, is illustrated in the image at
right:
Reducing and reusing commands

Commands are typically shown based on context, in order to reduce the number of commands the user sees at any given
time. However, you should also reuse existing shared menus and command groups to ensure that the command structure
remains relatively stable between changes in context.
Reusing shared commands and placing new commands close to related shared commands reduces IDE complexity and
creates a more user-friendly experience.
Menus and Commands: Naming commands

Naming conventions
Consistent command naming is critical so that users can find and execute commands, either by using the command line or
binding to a keyboard shortcut. Command names also help the user understand what purpose a command serves when it
is displayed on a toolbar or in a cascading or context menu.
When naming commands:
Construct text so that it is easily localizable. For more about localizing text, see World Readiness.
Be concise. Commands should use no more than three words.
Use title-case capitalization: the first letter of each word should be capitalized. For more information about text
formatting in Visual Studio, see Text style.
Take into consideration where the command will be placed. Is it in a top-level menu or a flyout?
For example, when grouping alignment commands in a flyout, the top-level command should be "Align and the
flyout commands should be "Left," "Right," "Center," "Justify," and so on. It would be redundant to name the
flyout commands "Align Left" or "Align Right.
Using icons with commands

Be sparing in the use of icon pairing with commands. Although associating a unique image with a command hastens the
user's ability to identify that command, visual clutter and inefficiency occur with image overuse. The following rules help
when deciding whether to create a command icon.
Use an icon with a command only if:
The same command has an icon associated with it in another prominent Microsoft product, such as one of the
Microsoft Office applications.
The command will be placed in a default toolbar.
The command is a specialty command that users are likely to add to a toolbar using the Customize dialog.

Menus and Commands: Access and shortcut keys

There are two kinds of keyboard key assignments:
Access keys (also known as Accelerators) allow keyboard access via the menus for commanding and to each label
in dialog UI. Access keys are mostly for accessibility purposes, are assigned to all menus and most dialog box
controls, are not meant to be memorized, affect only the current window, and are localized.
Shortcut keys mostly use Control (Ctrl) and Function (Fn) key sequences. They are designed more for advanced
users and aid in productivity. They are assigned only to the most-often used commands and allow quick access
while bypassing the main menu. Shortcut keys are intended to be memorized, and for that reason must be
assigned consistent with the profile scheme. Shortcut key schemes may vary from profile to profile. A user may
customize shortcut keys through Tools > Options > Keyboard.
Assigning access keys

Access keys consist of Alt plus alphanumeric key(s). Assign an access key to each menu item without exception. Follow
Windows and common conventions for assigning access keys. for example, the access key for File > New should always be
Alt, F, N.
Do not use single-pixel-width letters such as 'i' (in uppercase or lowercase) or a lowercase 'l.'
Avoid using characters with descenders (g, j, p, q, and y), as these are difficult to distinguish.
Avoid using duplicate keys when possible. In cases where duplication is unavoidable, the menu system handles
conflicts by cycling through all commands that use the key. As an example, for a hypothetical "Number" command
under the File menu that duplicates the "N" access key, Alt, F, N would create a new file, and Alt, F, N, N would
perform the "Number" command.
Assigning shortcut keys

Avoid assigning new shortcut keys, because they are not required for every command and tax the system (and user
memory) if overused. Data from the Customer Experience Improvement Program (CEIP) indicates that Visual Studio users
use only a small subset of the integrated shortcuts.
When defining shortcuts, follow these rules:
Use Control (Ctrl) and Function (Fn) key sequences.
Preserve frequently used shortcuts. Maintain the most popular shortcuts.
Make editor shortcuts easy to type. Bind easy-to-type shortcuts to commands that developers need most while
writing code. For example, Edit.InvokeSmartTag needs to have a quick shortcut key like Ctrl+/ and not
Alt+Shift+F10.
Strive for consistently themed shortcuts.
Follow Windows guidelines to determine which modifier keys to employ. Use Ctrl key combinations for
commands that have large-scale effects, such as commands that apply to an entire document. Use Shift key
combinations for commands that extend or complement the actions of the standard shortcut key. Don't use
Ctrl+Alt combinations.
Remove extraneous shortcuts. If you have a legacy feature, consider removing shortcuts that are used with
extreme infrequency (fewer than 10 times from the CEIP data) or moderate infrequency (fewer than 100 times
from the CEIP data) if an access key provides quick access to the same command. For example: Alt, H, C will open
Help > Contents.

There is not a simple way to check shortcut availability. If you want to add a shortcut, follow these steps:
1.
Check the list of Visual Studio 2013 shortcuts to determine if there are similar commands to group yours with.
2.
Go to Tools > Options > Environment > Keyboard and test your shortcut. Check each keyboard mapping scheme
listed under "Apply the following additional keyboard mapping scheme." Check General, C#, VB, and C++ profiles,
as those share unique shortcuts. Your shortcut is available if it's not mapped in any of those places.

6: UI Text and Help

2015 RC PREVIEW
UI Text and Help: UI text and terminology

Comprehensible text is crucial to effective UI. Software users tend to read labels first, namely those most relevant to
completing the task at hand. Static text is read with less frequency. Plan for users to start their work sessions with a quick
scan of the whole window, followed by a reading of the UI in this approximate order:
1.
Interactive controls in the center
2.
Commit buttons
3.
Interactive controls found elsewhere
4.
Main instruction
5.
Supplemental explanations
6.
Window title
7.
Other static text in the main body
Usage patterns for UI text

Title bar text
Title bar text must match the command that spawned the UI.
Instructional text (helper text)

In some dialogs, it is helpful to provide prominent main instructions to explain what to do in the window or in the page.
This is sometimes referred to as "helper text."
Basic rules
Don't explain the obvious. Unless it is absolutely needed, do not include instructional text.
Instructional text is always placed at the top of the dialog and should refer to the task being performed.
Precisely explain to users what they need to do. Avoid excessive communication and redundancy.
Review each window and eliminate duplicate words and statements.
Keep instructional text short. If more information is necessary for certain users or scenarios, then provide a link to
a detailed conceptual online topic.
Write your text so that every word holds weight and is necessary.
Follow existing Microsoft guidance for User Interface Text and Style and Tone.
170 Visual Studio UX Guidelines: UI Text and Help

Supplemental instructions
Supplemental instructions provide additional information that helps the user understand controls or control groupings.
This could also include hint text necessary to understand what format the input control is expecting. Use supplemental
instructions sparingly in cases where its unlikely that the user will fully understand the ramifications of the choice they are
making.
Two examples of supplemental text
InfoTips
Often, the instructional text might be too lengthy to
position in-place in the UI or might be useful only to new
users, feeling like clutter to experienced users. In this
case, the instructional/informational text should be
placed as a tooltip under an InfoTip.
InfoTips should be placed near the controls that they are
related to and should use the specific InfoTip icon, which
is unobtrusive yet noticeable.
Basic writing style rules
Write InfoTips as complete sentences. They require specific verbs, sentence case, and ending punctuation.
Use InfoTips to supplement your main instruction or information. If you are just using different words to
restate the main idea, you don't need an InfoTip.
Keep InfoTips short and sweet. Use small words and plain, everyday language that supports and encourages
the user.
Follow existing Microsoft guidance for User Interface Text and Style and Tone.
Control labels
Control labels should be short, concise, and follow the Windows Desktop guidance for Controls.
For more information about control label format and placement within the UI, see Dialog layout.
Visual Studio UX Guidelines: UI Text and Help 171

Help links
Help links can either be placed within instructional text or in the body of the UI. They can be links to Help or launch
internal dialogs.
Basic visual style rules
Use the correct environment colors for hyperlinks. A properly styled hyperlink will not briefly flash red when
clicked. If you see this, then it is an indication that environment colors are not being used.
Underlines should only be used on hover or when the link is embedded in a paragraph.
For more detailed information on visual and interaction styles for hyperlinks, see Buttons and hyperlinks.
Basic writing style rules
When launching dialogs, maintain the standards for ellipses: no ellipsis for navigation, ellipses if the task requires
additional UI.
Example:
Links should not start with "Learn," as that's not the user's intent. The user wants to answer a specific question, not
receive a general education.
Phrase help links so that they ask the question that the topic will answer.
Incorrect: "Learn about Windows Azure Mobile Services pricing"
Correct: "What pricing options are available for Windows Azure Mobile Services?"
Never use Click to the link text.
Never link only the word "here." This is problematic for some screen readers, which will voice only the hyperlinked
word.
Incorrect: "Find information on Windows Azure Mobile Services here"
Correct: "What pricing options are available for Windows Azure Mobile Services?"
For more information on the correct writing style for Help links, see the Windows Desktop guidance for Help.
Hint text
Hint text appears as a watermark within a control or below the control. Correct formatting will be applied by using the
appropriate VSColors token, Environment.GrayText.
It can appear in a number of forms:
In place of the control label
With a verb, giving instructions
With text indicating a required entry

Watermark text
On an empty design surface, the text should indicate what to do as well as provide links to open other related windows, if
appropriate:
Common terminology
Term
Explanation
Comment
Sign in / Sign out
Verbs used synonymously with the web
The IDE User is the only feature that
for representing authentication into a web
should represent a sign in / sign out verb,
property. Within clients, we use this once
as it represents the top-level IDE user.
as a top-level notion for signing in and

out of IDE user connection, which
represents a top-level identity that
provides higher-level capabilities such as
roaming and licensing that are not
available with all other connections.
Connect / Disconnect
Use in places where a feature maintains a
Server Explorer, where you can only have
single connection to an online service.
one active Azure connection at a time, is

an example of Connect/Disconnect.
Add / Remove
Delete
Non-destructive. Use when adding or
The TFS Connection Manager server list
removing something from a list.
dialog is an example of Add/Remove.
Destructive. Use only when the element
"Delete" generally requires a prompt if the
being removed will be permanently
result is deleting a file from disk.
discarded or deleted from the disk.
Related topics
Fonts and Formatting
UI Text and Help: Error messages
UI Text and Help: Accessing Help
Layout
Notifications and Progress: Progress indicators

UI Text and Help: Error messages

Errors happen. Setting limitations on what the user can do is a sensible first step in preventing avoidable error messages.
However, when an error does occur, a well-written error message can go a long way toward mitigating the problem. Error
messages are arguably one of the most important types of notification that the user sees, because they are synchronous
and indicate a problem that needs to be solved. Poorly written error messages leave users on their own to decide the
cause of the errors and any possible solutions.
Users might stop paying attention to overused or confusing error messages, so write only necessary messages that add
value to the user experience. If the message is simply a notification, then use an alternative presentation.
Rules for creating an error message
When constructing error messages, choose the appropriate error level for the audience. Aim for straightforward
summaries that provide an action the user can take, if applicable. Don't state anything that the user does not need
to know.
Provide constructive assistance. It's easier to read and act on an error message that contains instruction.
Don't use internal terms and abbreviations that the user is unlikely to understand. Don't expose internal APIs in
the message.
Don't use double negatives.
Perform both an automated and a manual grammar and spelling check on any error message you write.
For complex error messages, avoid sequential communications. Never use an F1 hookup for the error message.
The message itself should be sufficient.
Use the correct icon.
Make questions easy to understand and use buttons that have clear choices, such as "Delete" and "Cancel."
For warnings, be clear about what the consequence of proceeding will be. The buttons should indicate the
consequence.
For errors, describe what the user can do to fix the problem. Buttons should be actions or say "Close." Don't use
an "OK" button for an error message.
Some questions to ask yourself when constructing an error message:

o
Can the user figure out how to solve the issue with this error alone?
Does the user use the same vocabulary as this error?
Is this error ambiguous or shared in multiple situations? If so, how do you guide users to the solution they
need?
Build errors
Since Visual Studio is a software development tool, many of its components have a compilation, converting, or encoding
step to convert the developers work to binary form. These conversions can cause errors when the compiler cannot
process improperly authored files or when compiler options werent set correctly.
Visual Studio users can spend an enormous number of development hours resolving build errors. This resolution time
increases when errors have dependencies or when error messages are poorly written, which can make it difficult to
uncover the source of the error.

The best build errors are those that don't occur in the first place, which is why Visual Studio provides AutoComplete and
IntelliSense squiggles. Schema validators and similar tools provide the same kind of feedback. These mechanisms
proactively guide the user to construct well-formed code, lessening the chance of build errors.
Visual Studio provides a tool window where users can read and navigate through the errors that occurred in their
document windows. Keyboard shortcuts are provided so that the user can quickly navigate large amounts of code and go
directly to the location of the problem. Visual Studio also allows each build error to be tied to a particular Help
keyword/context ID so that the user can go directly to a Help topic that gives more in-depth information about the error.
Write clear, concise build errors:
Use plain language that explains the problem with little or no compiler jargon. The text of a build error should not
be overly technical.
Outline possible causes. For example, Missing a colon between the property and value in the (property) : (value)
declaration.
Give details about potential fixes. If there is not enough room, then additional details may be put into the
corresponding Help topic.
Components of a well-written error message

Use the shell dialog service for error messages.
Using the shell dialog service lets you control the appearance of the message fonts in particular without major
changes to individual elements. Use the IErrorInfo mechanisms and report them using
IVsUIShell::SetErrorInfo/ReportErrorInfo.
Choose an effective and appropriate notification presentation.

Use a modal dialog with a critical warning if immediate action is required to avoid loss of data (synchronous notification).
Critical icons are reserved for situations in which closing the message without reading it can lead to negative
consequences. Loss of data is a critical situation that requires an alarm-level response. Overuse of the critical icon
desensitizes users to its importance. If the error message is informational in nature, consider alternatives to a modal dialog
(asynchronous notification).
Provide a clean, succinct explanation of why the problem occurred rather than a technical explanation.
Overburdening users with technical details in the explanation will make them more likely to ignore error messages.
Examples of good messaging:
"Unable to open the requested file."
"Unable to connect to the Internet."
Provide information about how to fix the problem.

Offer the user suggestions of how to fix the problem. Be honest with the user if there are no suggestions. Provide direct
links to alternative online sources, such as technical support or community support. Try to point users to specific online
information pertinent to the issue. For an error ID, consider linking users to a discussion thread about that specific error.
Examples of good messaging:
"Make sure that you are connected to the Internet and try this operation again."
"Make sure that the file exists and that you have permission to open it."

Write a message that is short and to the point.

An error message can notify, explain, and offer a solution but still be ignored if its too wordy. One solution is to use
progressive disclosure with a details button. For example, give a short description/solution and then put more details
under a details button. If users choose to read more information on the error, they can do so.
The language in the message should be:
Domain-appropriate. Use language the user will understand. Even though our customers are developers, they
often don't have the context and terminology we have.
Specific. Avoid vague wording and give specific names and locations of objects involved. For example, an error
message such as "character is invalid" is not useful. Which character? "File not found." Which file?
Courteous. Don't blame the user or make them feel stupid. Avoid hostile or offensive language (kill, execute,
terminate, fatal, illegal). Avoid uppercase text, which is often seen as shouting and is not as readable. Don't use
humor.
Correct. Use correct spelling and grammar (even in alphas). Typos are unprofessional and embarrassing.
Contextually appropriate. Use appropriate button text. Avoid the "OK" button and instead use "Continue" or
"Yes/No.
Examples
Good
"The number you dialed

is no longer in service.
Please check the number
and dial again or dial 0
for the operator."
Bad
"Error (449): Illegal number."

"This unhandled exception error indicates that the operation completed
successfully."

UI Text and Help: Accessing Help (F1)

In addition to documentation in MSDN, a Visual Studio user has several access points to user assistance in the UI. To
ensure that these access points are consistently available, feature teams need to take advantage of the Help system
offered by the environment. These access points are:
Instructional and supplemental text in dialogs. Static text that gives direction or explanation, either on the UI
surface or available on hover over an InfoTip icon.
F1 help (editor only). Within the Visual Studio editor, a user can trust that at any time, pressing F1 will bring up a
Help topic specific to the current selection. Ensure that topics associated with F1 are appropriate and informative.
Helper text in dialogs. Static text in the UI that gives direction or explanation.
Hyperlinks to Help topics. A hyperlink within a dialog, tool window, or design surface that launches a topic to
assist the user in learning more about a technology, capability, or information about how to accomplish a task.
Helper UI mechanisms, such as smart tags and building dialogs. These mechanisms assist the user in
understanding a UI element, or facilitate a task, such as smart tags or builder dialogs.
UI help buttons (deprecated). Visible indicators that give access to the related F1 Help topic.
Text
Instructional and supplemental text in dialogs
In dialogs that support complex tasks, there might be a need to give instructional text within the UI, often at the top of the
dialog or near complex controls. See UI text and terminology for details on writing style.
InfoTips
Often, instructional text might be too lengthy to position in place in the UI or might be useful only to new users, feeling
like clutter to experienced users. In this case, the instructional/informational text should be placed as a tooltip under an
InfoTip.
InfoTips should be placed near the controls that they are related to and should use the specific InfoTip icon, which is
unobtrusive yet noticeable.

Interactive Help mechanisms

F1 help
F1 help is required within an editor or design surface, but not elsewhere in the Visual Studio environment.
Hyperlinks to help topics

Hyperlinks can be used to perform an action, navigate within the IDE, or launch Help in a browser. See UI text and
terminology for details on language and Buttons and hyperlinks for visual and layout guidelines.
Help [?] buttons in dialog title bars (deprecated)

For the most part, the Help [?] buttons in the title bar of dialogs are deprecated. UI topics are no longer part of our doc
model, and therefore there might not be a relevant topic to link to. Essentially, the title bar button was the same thing as
F1 Help, and that is no longer required in dialogs. In some instances, this can still be used as an indicator that there is
more conceptual or procedural information available, although hyperlinks are more commonly used in newer UI.
If you do need to create a Help [?] button, here are the implementation details:
Dialogs created through the environment

Many shell dialogs are created through the VBDialogBoxParam function. This shared function was updated to assist in
moving the Help button from the dialog to the ? button while retaining an architecture that is backward compatible and
extensible.
Specifically, the VBDialogBoxParam function looks at the dialog template for a button whose ID is IDHELP (9) or label is
Help or &Help. If a Help button is found, it is hidden and the WS_EX_CONTEXTHELP style is added to the dialog, which
places the ? button in the dialog's title bar.
When the dialog is created, it pushes the dialog proc onto a stack and invokes the dialog with a pre-processing dialog
proc named DialogPreProc. When the ? button is clicked it sends a WM_SYSCOMMAND of SC_CONTEXTHELP to the
dialog. The DialogPreProc captures this command and changes it to a WM_HELP message, which is passed to the original
dialog proc.
Most environment-created dialogs have a Help button on the dialog. When the dialog is displayed, the Help button is
auto-hidden and only the ? button works. If the ? button is ever removed or changed in Windows, this solution allows you
to quickly move back to the original Help buttons.
This solution makes four assumptions which could cause bugs:
The dialog's help button is IDHELP (9).
The dialog looks correct when the Help button is hidden.
The dialog does not substitute its winproc.
The dialog is not embedded inside of another dialog.
If your dialog resides within msenv and doesn't use VBDialogBoxParam, investigate leveraging VBDialogBoxParam before
implementing your own handler.

Dialogs created through other packages

You can implement your own solution for dialogs that reside outside msenv. For a shared dialog class in your VSPackage,
consider moving the button to the title bar or implementing a handler on each dialog. The following code is a skeleton of
an implementation to help you get started:
struct DLGPROCITEM
{
FARPROC proc; // The info used to create the dialog.
DLGPROCITEMZ* procPrev;
};
DLGPROCITEM* g_dlgProcStack = NULL;
// A dialog starter/wrapper function is used to push the new
// dialog proc to the top of our dialog proc stack.
int SomeDialogStarterFunction(hinst, id, proc, etc)
{
if (g_dlgProcStack == NULL)
{
g_dlgProcStack = new DLGPROCITEM;
g_dlgProcStack->procPrev = NULL;
}
else
{
DLGPROCITEM* procItem = new DLGPROCITEM;
g_dlgProcStack->procPrev = g_dlgProcStack;
g_dlgProcStack = procItem;
}
}
// Pop this dialog proc off the dialog proc stack.
DialogBoxIndirectParam...(...)
{
DLGPROCITEM* procItem = g_dlgProcStack->procPrev;
delete g_dlgProcStack;
g_dlgProcStack - procItem;
}
// A wrapper dialog procedure will allow us to capture the
// SC_CONTEXTHELP button on the title bar from Windows and
// forward it as a simple WM_HELP message back to the dialog.
INT_PTR CALLBACK DialogPreProc(HWND hwndDlg, UINT uMsg,
WPARAM wParam, LPARAM lParam)
{
if (uMsg == WM_SYSCOMMAND && wParam == SC_CONTEXTHELP)
{
uMsg == WM_HELP;
wParam = 0;
lParam = 0;
}
return CallWindowProc((WNDPROC)g_dlgProcStack->proc,
hwndDlg, uMsg, wParam, lParam);
}
Help buttons in managed code

Overriding the window title bar Help button's default behavior is easy in managed code. Below is a complete demo
application that demonstrates this behavior. In essence, you need to override your form's WndProc method and then fire
off F1 help requests when an SC_CONTEXTHELP message is intercepted.
using System;
using System.Windows.Forms;
public class Helpform : Form
{
private const int SC_CONTEXTHELP = 0xF180;
private const int WM_SYSCOMMAND = 0x0112;
public HelpForm()
{
this.ClientSize = new SystemDrawingSize(300,250);
this.HelpButton = true;
this.MaximizeBox = false;
this.MinimizeBox = false;
this.Name = "HelpForm";
this.Text = "Help Form";
}
protected override void WndProc(ref Message m)
{
if (m.Msg == WM_SYSCOMMAND && SC_CONTEXTHELP == (int)m.WParam)
ShowHelp();
else
base.WndProc(ref m);
}
private void ShowHelp()
{
MessageBox.Show("F1 Help goes here.");
}
[STAThread]
static void Main()
{
Application.EnableVisualStyles();
Application.EnableRTLMirroring();
Application.Run(new HelpForm());
}
}

7: Interaction Patterns

2015 RC PREVIEW
Interaction Patterns: Visual Studio patterns overview

A design pattern, in general, is the core of a design that can be applied in specific situations to solve problems with similar
sets of constraints. Feature and system designers use these design patterns as starting points, which can then be adapted
to their specific situation.
Visual Studio has a library of common interaction patterns that should be considered when building new features. There
are two core contexts for our design patterns: Visual Studio Client (devenv) and Visual Studio Online. For some design
problems, there is a ubiquitous pattern that works well in all situations. In many cases, however, the solution might be
different for UI that is being presented within a browser and that which is hosted on a client application.
Pattern type
Description
Examples
Application-level patterns
High-level patterns common to the application, determining or
Tool windows
displaying application context, and containing composite and
Document windows
Common patterns that may span across application patterns, or a
View switching
recognized pattern made up of several controls in a distinct
List builders
configuration
Displaying data
Notifications
Validations
Selection models
Tree views
Editing within a grid control
control patterns within them

Composite patterns
Control patterns
Specifics about how low-level controls are expected to behave
Application patterns
At a high level, the Visual Studio interface comprises multiple windows, dialogs, commands, and toolbars within a single
IDE. The Visual Studio hierarchy determines context and drives menus. The key integration points in the user interface of
the IDE are document windows, tool windows, projects, the command structure, the text editor, the toolbox, the Properties
window, and Tools > Options.
There are basic usage patterns for each of the key integration points in the user interface of the IDE:
5: Menus and Commands

7: Interaction Patterns > Application patterns
Window interactions
Tool windows
Document editor conventions
Dialogs
Projects
Common control patterns

Control patterns are mainly about how individual controls are expected to behave. This is one area in which consistency is
most critical.
Most common controls in Visual Studio should follow the Desktop Windows guidelines. Our guidelines document only
includes areas in which we need to augment common conventions with Visual Studio-specific interactions, or places in
182 Visual Studio UX Guidelines: Interaction Patterns

EARLY PARTNER PREVIEW OF 2015 GUIDELINES. SUBJECT TO CHANGE. FOR QUESTIONS OR FEEDBACK, EMAIL UXBOARD@MICRO SOFT.COM.
which we supersede the guidelines entirely in order to tailor Visual Studio to meet the needs of our sophisticated, techsavvy users.
7: Interaction Patterns > Common control patterns

Common controls
Search
Text controls
Buttons and hyperlinks
Lists and grids
Tree views
Composite patterns
There are a number of ways that users expect to accomplish tasks. Wherever possible, features should be designed to use
those patterns both for interaction and visual design.
While there are many composite patterns within Visual Studio, some of the most important with regards to consistency
are:
7: Interaction Patterns > Composite patterns

On-object UI and peeking
Selection models
Persistence and saving settings
Touch input
Visual Studio UX Guidelines: Interaction Patterns 183

Application patterns: Window interactions

The two main window types used in Visual Studio are document editors and tool windows. Rare, but possible, are large
modeless dialogs. Although these are all modeless in the shell, their patterns are fundamentally different. This topic covers
the difference between document windows, tool windows, and modeless dialogs. Modal dialog patterns are covered in
Application patterns: Dialogs.
Comparing window usage patterns

Document windows are almost always displayed within the document well. This gives the document editor a center
stage to arrange supplemental tool windows around.
A tool window is most often displayed as a separate, smaller window which can be visible, hidden, or auto-hidden
collapsed against the edge of the IDE. However, sometimes they are presented within the document well, by unchecking
the Window/Docking property on the window. This results in more real estate, but also a common design decision: when
attempting to integrate into Visual Studio, you must decide whether your feature should display a tool window or a
document window.
Modeless dialogs were discouraged in previous versions of Visual Studio. To a large extent, they were by definition
floating tool windows and should have been implemented as such. With the new modern designs, however, modeless
dialogs are allowed in cases where the size of a normal tool window docked to the side of the shell would be too limiting.
They are also allowed in cases where the user would be likely to move the dialog to a secondary monitor.
When designing UI, consider carefully which container type that you use. There are common usage patterns to consider,
as outlined below:
Document window
Tool window
Modeless dialog
Position
Always positioned within the document

well and does not dock around the
edges of the IDE. It can be pulled off
so that it floats separately from the
main shell.
Generally tab-docked around the edges

of the IDE, but can be customized to be
floating, auto-hidden (unpinned), or
docked within the document well.
Large floating window

separate from the IDE.
Commit model
Delayed commit
In order to save the data in a document,
the user must issue the File/Save, Save
As, or Save All command. A document
window has the concept of the data
within it being "dirtied" then committed
to one of the save commands. When
closing a document window, all
contents are either saved to disk or lost.
Immediate commit
There is no save model. For inspector
tool windows that assist in editing a file,
the file must be open in the active
editor or designer, and the editor or
designer owns the save.
Delayed or immediate commit

Most often, a large modeless
dialog requires an action to
commit changes and allows
for a Cancel operation, which
rolls back any changes made
within the dialog session.
Visibility
Open/Create (file) and Close

Opening a document windows is done
through either opening an existing
document or using a template to create
a new document. There is no Open
<specific editor> command.
Hide and show

Single-instance tool windows can be
hidden or shown. Contents and states
within the tool window persist whether
in view or hidden. Multi-instance tool
windows can be closed as well as
hidden. When a multi-instance tool
window is closed, the content and state
within the tool window is discarded.
Launched from a command

Dialogs are launched from a
task-based command.

Instances
Examples
Document window
Tool window
Modeless dialog
Multi-instance
Several editors can be open at the same
time and editing different files, while
some editors also allow the same file to
be open in more than one editor (using
the Window > New Window
command).
Single or multi-instance
Single instance
Some single-instance tool windows
might be associated with the active
document window. While multi-instance
tool windows might not, it is generally
advisable for them to have that
association.
A single editor may be editing one or

multiple files at the same time (Project
Designer).
Contents change to reflect context (as in

the Property Browser) or push
focus/context to other windows (Task
List, Solution Explorer).
Text editors, such as the code editor

Design surfaces, such as a form
designer or a modeling surface
Control layouts similar to dialogs, such
as the Manifest Designer
The Solution Explorer, which provides a

solution and projects contained within
the solution.
The Server Explorer, which provides a
hierarchical view of servers and data
connections that the user chooses to
open in the window. Opening an object
from the database hierarchy, such as a
query, opens a document window and
allows the user to edit the query.
The Property Browser, which displays
properties for the object selected either
in a document window or another tool
window. The properties are presented
either in a hierarchical grid view or in
complex dialog-like controls and allow
the user to set the values for those
properties.

Application patterns: Tool windows

Tool windows support the user's work that happens in document windows. They can be used to display a hierarchy that
represents a fundamental root object that Visual Studio provides and can manipulate.
When considering a new tool windows in the IDE, authors should:
Use task-appropriate existing tool windows and not create new ones with similar functionality. New tool windows
should only be created if they offer a significantly different tool or functionality that cannot be integrated into a
similar window, or by turning an existing window into a pivoting hub.
Use a standard command bar, if needed, at the top of the tool window.
Be consistent with patterns already present in other tool windows for control presentation and keyboard
navigation.
Be consistent with control presentation in other tool windows.
Document-specific tool windows should be auto-visible when possible so that they appear only when the parent
document is activated
Ensure their window content is navigable by the keyboard (support arrow keys).
Tool window states

Visual Studio tool
windows have different
states, some of which
are user-activated (like
the auto-hide feature).
Other states, such as
auto-visible, allow tool
windows to appear in
the correct context and
hide when not needed.
There are five tool
window states in total.
Docked/pinned
tool windows
can be attached
to any of the
four sides of the document area. The pushpin icon appears in the tool window title bar. The tool window can be
docked horizontally or vertically along the edge of the shell and other tool windows, and can also be tab-linked.
Auto-hidden tool windows are unpinned. The window can slide out of sight, leaving a tab (with the name of tool
window and its icon) on the edge of the document area. The tool window slides out when a user hovers over the
tab.
Auto-visible tool windows automatically appear when another piece of UI, such as an editor, is launched or gains
focus.
Floating tool windows hover outside the IDE. This is useful for multi-monitor configurations.
Tabbed document tool windows can be docked within the document well. This is useful for large tool windows,
such as the Object Browser, that need more real estate than docking to the edges of the frame allows.

Single-instance and multi-instance
Figure A
Tool windows are either single-instance or multi-instance. Some

single-instance tool windows might be associated with the active
document window, while multi-instance tool windows might not.
Multi-instance tool windows respond to the Window/New Window
command by creating a new instance of the window. Figure A
illustrates a tool window enabling the New Window command when
an instance of the window is active.
Single-instance tool windows can be hidden or shown, while multi-instance
Figure B
tool windows can be closed as well as hidden. All tool windows can be docked,
tab-linked, floating, or set as a Multiple-Document Interface (MDI) child
window (similar to a document window). All tool windows should respond to
the appropriate window management commands in the Window menu, as
shown in Figure B.
Document-specific tool windows

Some tool windows are designed to change based on a given type of
document. These windows continually update to reflect functionality applicable
to the active document window in the IDE.
Examples of tool windows whose contents change to reflect the selected editor
are the Toolbox and the Document Outline. These windows show a watermark
when an editor has focus that does not offer context to the window.
Navigable list tool windows

Some tool windows display a list of navigable items the user can interact with.
In this type of window, there should always be feedback for the current item in the list, even if the window is inactive. The
list should respond to the GoToNextLocation and GoToPrevLocation commands by also changing the currently selected
item in the window.
Examples of navigable list tool windows are the Solution Explorer and the Find Results window.
Tool window types

Instead of creating new tool windows, packages should integrate into existing tool windows that provide similar
functionality. As the list of tool windows grows, so does the burden of window management, which falls on the user. If
creating a new tool window is necessary, try to use an existing similar window as an example. The next page features a list
of common tool windows and their functions.

Common tool windows and their functions

Type
Tool window
Function
Hierarchy
Solution Explorer
A hierarchical tree that displays a list of documents contained in projects, miscellaneous

files, and solution items. The display of the items within projects is defined by the package
that owns the project type (for example, reference-based, directory-based, or mixed-mode
types).
Class View
A hierarchical tree of the classes and various elements in the working set of documents,
independent of the files themselves.
Grid
Server Explorer
A hierarchical tree that displays all the servers and data connections in the solution.
Document Outline
The hierarchical structure of the active document.
Properties
A grid that displays a list of properties for the selected object, along with value pickers to
edit those properties.
Content
Task List
A grid that allows the user to create/edit/delete tasks and comments.
Help
A window that allows users access to various methods of getting help, from How Do I?
videos to MSDN forums.
Dynamic Help
A tool window that displays links to help topics applicable to the current selection.
Object Browser
A two-column frameset with a list of hierarchical object components in the left pane and the
object's properties and methods in the right column.
Dialog
Find, Advanced Find
A dialog that allows the user to find or find and replace in various files within the solution.
Other
Toolbox
The tool window used to store elements that will be dropped onto design surfaces,
providing a consistent drag-source for all designers.
Start Page
The user's portal to Visual Studio, with access to feeds of developer news, Visual Studio
help, and recent projects. Users can also create custom start pages by copying the
StartPage.xaml file from the Common7\IDE\StartPages\ Visual Studio program files
directory to the StartPages folder in the Visual Studio documents directory, and then either
editing the XAML by hand or opening it in Visual Studio or another code editor.
Debugger: a
Autos
group of
Immediate
windows
Output
specific to
debugging
tasks and
monitoring
activities
The output window can be used whenever you have textual events or status to declare.
Memory
Breakpoints
Running
Documents
Call Stack
Locals
Watches
Disassembly
Registers
Threads

Application patterns: Document editor conventions

Document interactions
The "document well" is the largest space within the IDE and is where the user generally has focused their attention in
order to complete their tasks, assisted by supplemental tool windows. Document editors represent the fundamental units
of work that the user opens and saves within Visual Studio. They retain a strong sense of selection tied to Solution
Explorer or other active hierarchy windows. The user should be able to point to one of those hierarchy windows and know
where the document is contained and its relationship to either the solution, the project, or another root object provided
by a Visual Studio package.
Document editing requires a consistent user experience. To allow the user to focus on the task at hand instead of on
window management and finding commands, select a document view strategy that best fits the user tasks for editing that
document type.
Common interactions for the document well
Maintain a consistent interaction model in the common New File and Open File experiences.
Update related functionality in related windows and menus when the document window opens.
Menu commands are appropriately integrated into common menus such as Edit, Format and View menus. If a
substantial amount of specialized commands are available, then a new menu can be created which is visible only
when the document has focus.
An embedded toolbar may be placed at the top of the editor. This is preferable to having a separate toolbar that
appears outside the editor.
Always maintain a selection in the Solution Explorer or similar active hierarchy window.
Double-clicking a document in the Solution Explorer should perform the same action as Open.
If more than one editor can be used on a document type, the user should be able to override or reset the default
action on a given document type using the Open With dialog box by right-clicking on the file and selecting Open
With from the shortcut menu.
Don't build a wizard in a document well.
User expectations for specific document types

There are several different basic types of document editors and each has a set of interactions that are consistent with
others of the same type.
Text-based editor: code editor, log files

Design surface: WPF forms designer, Windows forms
Dialog-style editor: Manifest Designer, project properties
Model designer: workflow designer, codemap, architecture diagram, progression
There are also several non-editor types that use the document well. While they don't edit documents themselves, they do
need to follow standard interactions for document windows.
Reports: IntelliTrace report, Hyper-V report, profiler report

Dashboard: Diagnostics Hub
Text-based editors
The document participates in the preview tab model, allowing for previewing the document without opening it.
The structure of the document may be represented within a companion tool window, such as a document outline.
IntelliSense (if appropriate) will behave consistently with other code editors.
Pop-ups or assistive UI follow similar styles and patterns for existing similar UI, such as CodeLens.
Messages regarding document status will be presented in an infobar control at the top of the document or in the
status bar.
The user must be able to customize the appearance of fonts and colors using a Tools > Options page, either the
shared Fonts and Colors page or one specific to the editor.
Design surfaces
An empty designer should have a watermark on the surface indicating how to get started.
View-switching mechanisms will follow existing patterns such as double-click to open a code editor, or tabs within
the document window allowing interaction with both panes.
Adding elements to the design surface should be done via the Toolbox, unless a highly specific tool window is
required.
Items on the surface will follow a consistent selection model.
Embedded toolbars contain document-specific commands only, not common commands such as Save.
Dialog-style editors
Control layout should follow normal dialog layout conventions.

Tabs within the editor should not match the appearance of the document tabs, they should match one of the two
allowed interior tab styles.
Users must be able to interact with the controls using keyboard only; either by activating the editor and tabbing
through controls or by using standard mnemonics.
The designer should use the common Save model. No overall Save or commit buttons should be placed on the
surface, although other buttons may be appropriate.
Model designers
An empty designer should have a watermark on the surface indicating how to get started.
Adding elements to the design surface should be done via the Toolbox.
Items on the surface will follow a consistent selection model.
Embedded toolbars contain document-specific commands only, not common commands such as Save.
A legend may appear on the surface, either interactive or a watermark.
The user must be able to customize the appearance of the fonts/colors using a Tools > Options page, either the
shared Fonts and Colors page or one specific to the editor.
Reports
Reports are typically information-only and don't participate in the Save model. However, they may include
interaction such as links to other relevant information or sections that expand and collapse.
Most commands on the surface should be hyperlinks, not buttons.
Layout should include a header and follow the standard report layout guidelines.
Dashboards
Dashboards don't have an interaction model themselves, but serve as a means to offer a variety of other tools.
They do not participate in the Save model.
Users must be able to interact with the controls using keyboard only, either by activating the editor and tabbing
through controls or by using standard mnemonics.

Application patterns: Dialogs

Dialogs in Visual Studio should typically support one discrete unit of the user's work and then be dismissed. If you have
determined that you need a dialog, you have three choices, in order of preference:
1.
Integrate your features into one of Visual Studios shared dialogs
2.
Create your own dialog using a pattern found in an existing similar dialog.
3.
Create a new dialog, following interaction and layout guidelines.
This topic describes how to choose the correct dialog pattern within Visual Studio workflows and the common
conventions for dialog design.
Themes
Dialogs in Visual Studio will follow one of two basic styles:
Standard (unthemed)
The majority of dialogs are standard utility dialogs and should be unthemed. Do not re-template common controls or
attempt to create stylized "modern" buttons or controls. Controls and chrome appearance follow standard Windows
Desktop interaction guidelines for dialog boxes.
Themed
Special signature dialogs may be themed. Themed dialogs will have a distinct appearance, which also has some special
interaction patterns associated with the style. Theme your dialog only if it meets these requirements:
The dialog is a common experience that will be seen and used often or by many users (for example, the New
Project dialog).
The dialog contains prominent product brand elements (for example, the Account Settings dialog).
The dialog appears as an integral part of a larger flow that includes other themed dialogs (for example, the Add
Connected Service dialog).
The dialog is an important part of an experience that plays a strategic role in promoting or differentiating a
product version.
When creating a themed dialog, use the appropriate environment colors (3: Colors and Styling) and follow the correct
layout and interaction patterns (8: Layout).
Dialog design
Well-designed dialogs take into consideration the following elements:
The user task being supported
The dialog text style, language, and terminology
Control choice and UI conventions
Visual layout specifications and control alignment
Keyboard access
Content organization
Consider the differences between these basic types of dialogs:
Simple dialogs, which present controls in a single modal window. The presentation might include variations of
complex control patterns, including a field picker or an icon bar.
Layered dialogs, which are used to make the most of screen real estate when a single piece of UI comprises
multiple groups of controls. The dialog's groupings are "layered" through tab controls, navigation list controls, or
buttons so that the user can choose which grouping to see at any given moment.
Wizards, which are useful for directing the user through a logical sequence of steps toward the completion of a
task. A series of choices are offered in sequential panels, sometimes introducing different workflows ("branches")
dependent on a choice made in the previous panel.
Simple dialogs
A simple dialog is a presentation of controls in a single modal window. This presentation might include variations of
complex control patterns, such as a field picker. For simple dialogs, follow the standard general layout as well as any
specific layout required for complex control groupings.
Create Strong Name Key is an example of a simple dialog in Visual Studio.
Layered dialogs: tabs, dashboards, and embedded trees

Layered dialogs are used to maximize real estate when there are multiple groups of controls offered in a single piece of UI.
The groupings are layered so that the user can choose which grouping to see at any one time.
In the most straightforward case, the mechanism for switching between groupings is a tab control. There are several
alternatives available; see Prioritizing and layering on how to choose the most appropriate style.
The Tools > Options dialog is an example of a layered dialog using an embedded tree:
Tools > Options is an example of a layered dialog in Visual Studio.

Wizards
Wizards are useful for directing the user through a logical order of steps in the completion of a task. A series of choices
are offered in sequential panels, and the user must continue through each step before proceeding to the next. Once
sufficient defaults are available, the Finish button is enabled.
Modal wizards are used for tasks that:
Contain branching, where different paths are offered depending on user choices.
Contain dependencies between steps, where subsequent steps depend on user input from the preceding step(s).
Are sufficiently complex that the UI should be used to explain the choices offered and the possible outcomes in
each step.
Common conventions
To achieve optimal design and functionality with your dialogs, follow these conventions on dialog size, position, standards,
control configuration and alignment, UI text, title bars, control buttons, and access keys.
For layout-specific guidelines see 8: Layout.
Size
Dialogs should fit within a minimum 1024x768 screen resolution, and initial dialog size should not exceed 900x700 pixels.
Dialogs may be resizable, but it is not a requirement.
There are two recommendations for resizable dialogs:
1.
That a minimum size is a defined for the dialog that will optimize for the control set without clipping, and adjust
to accommodate reasonable localization growth.
2.
That the user-scaled size persists from session to session. For example, if the user scales a dialog to 150%, then a
subsequent launch of the dialog will display at 150%.
Position
Dialogs must appear centered within the IDE (integrated development environment) on first launch. For non-resizable
dialogs, it is not required that the last position of the dialog be persisted, so it may appear centered on subsequent
launches. For resizable dialogs, on subsequent launches the size and position should be persisted.
When dialogs must spawn other dialogs, the topmost dialog should cascade to the right and down from the parent so
that it is obvious to the user that they have navigated to a new place.
Modality
Being modal means that users are required to complete or cancel the dialog before continuing. Since modal dialogs block
the user from interacting with other parts of the environment, your feature's task flow should use them as sparingly as
possible. When a modal operation is necessary, Visual Studio has a number of shared dialogs you can integrate your
features into. If you must create a new dialog, follow the interaction pattern of an existing dialog with similar functionality.
When users need to perform two activities at once, such as Find and Replace while writing new code, the dialog should be
modeless so that the user can easily switch between them. Visual Studio generally uses tool windows for this kind of
editor-supporting linked task.

Control configuration
Be consistent with existing control configurations that accomplish the same thing in Visual Studio.
Title bars
The text in the title bar must reflect the name of the command that launched it.
No icon should be used in dialog title bars. In cases where the system requires one, use the Visual Studio logo.
Dialogs should not have minimize or maximize buttons.
Help buttons in the title bar have been deprecated. Do not add them to new dialogs. When they do exist, they
should launch a Help topic that is conceptually relevant to the task.
Control buttons
In general, OK/Cancel/Help buttons should be arranged horizontally in the lower right corner of the dialog. Use of the
alternate vertical stack is permitted if a dialog has several other buttons at the bottom of the dialog that would present
visual confusion with the control buttons.
Acceptable configurations for control buttons in Visual Studio dialogs
The dialog must include a default control button. To determine the best command to use as the default, choose from the
following options (listed in order of precedence):
Choose the safest and most secure command as the default. This means choosing the command most likely to
prevent data loss and avoid unintended system access.
If data loss and security aren't factors, then choose the default command based on convenience. Including the
most likely command as the default will improve the users workflow when the dialog supports frequent or
repetitive tasks.
Avoid choosing a permanently destructive action for the default command. If such a command is present, choose a safer
command as the default instead.

Access keys
Do not use access keys for OK/Cancel/Help buttons. These buttons are mapped to shortcut keys by default, which suffice
for quick keyboard access:
Button name
Keyboard shortcut
OK
Enter
Cancel
Esc
Help
F1
Imagery
Use images sparingly in dialogs. Do not use large icons in dialogs merely to use up space. Use images only if they are an
important part of conveying the message to the user, such as warning icons or status animations.
Prioritizing and layering

Prioritizing your UI
It might be necessary to bring certain UI elements to the forefront and place more advanced behavior and options
(including obscure commands) into dialogs. Bring commonly used functionality to the forefront by making room for it,
and by making it visible by default in the UI with a text label when the dialog is shown.
Layering your UI
If you have determined that a dialog is necessary but the related functionality you want to present to the user goes
beyond what can be displayed in a simple dialog, then you need to layer your UI. The most common layering methods
Visual Studio uses are tabs and hallways or dashboards. In some cases, regions that can expand and collapse might be
appropriate. Adaptive UI is generally not recommended in Visual Studio.
There are advantages and disadvantages to different methods of layering UI through tab-like controls. Review the list
below to ensure that you are choosing a layering technique that is appropriate to your situation.
Tabbing
Switching mechanism
Advantages and appropriate use
Disadvantages and inappropriate use
Tab control
Logically group dialog pages into related
Making descriptive short labels can be difficult

Generally doesn't scale past five tabs in one dialog
Inappropriate if you have too many tabs for one
Sidebar navigation
sets
Useful for fewer than five (or the number of
tabs that fit in one row across the dialog)
pages of related controls in dialog
Tab labels must be short: one or two words
that can easily identify the content
A common system dialog style
Example: File Explorer > Item Properties
Simple switching device that can
accommodate more categories than tabs

Flat list of categories (no hierarchy)
Extensible
Example: Customize > Add Command
row (use an alternative layering technique)
Not extensible
Not a good use of horizontal space if there are

fewer than three groups
Task might be better suited to a drop-down

Switching mechanism
Advantages and appropriate use
Disadvantages and inappropriate use
Tree control
Allows for unlimited categories

Allows for grouping and/or hierarchy of
Heavily nested hierarchies can cause excessive
categories
Extensible
Example: Tools > Options
Wizard
horizontal scrolling
Visual Studio has an overabundance of tree views
Aids in task completion by guiding through
Inappropriate for any task that does not require a

task-based, sequential steps. The wizard
sequential workflow
represents a high-level task and the
Users can become overwhelmed and confused by
individual panels represent subtasks needed
a wizard with too many steps
to accomplish the overall task.
Wizards have inherently limited screen real estate
Useful when the task crosses UI boundaries,
as when the user would otherwise have to
use multiple editors and tool windows to
complete the task.
Useful when the task requires branching
Useful when the task contains dependencies
between steps
Useful when several similar tasks with one
decision fork can be presented in one dialog
to reduce the number of different similar
dialogs
Hallways or dashboards
These are dialogs or panels that are launching points to other dialogs and windows. The well-designed hallway/dashboard
has common options, commands, or settings so the user can accomplish common tasks while retaining access to
additional functionality. If you don't provide common options, the hallway becomes a simple dashboard.
Hallway or dashboard concept for exposing additional UI in Outlook
Adaptive UI
Showing or hiding UI based on usage or a user's self-reported experience is another way of presenting necessary UI
while hiding other portions. This is not recommended in Visual Studio as the algorithms for deciding when to show or
hide UI can be tricky, and the rules will always be wrong for some set of cases.
Application patterns: Projects

Most projects are classified as reference-based, directory-based, or mixed. All three types of projects are supported
simultaneously in the Solution Explorer. The root of the user experience in working with projects takes place inside this
window. Although different project nodes are reference, directory, or mixed-mode type projects, there is a common
interaction pattern that should be applied as a starting point before diverging into project-specific user patterns.
Projects should always:
Support the ability to add project folders to organize project contents.

Maintain a consistent model for project persistence.
Projects should also maintain consistent interaction models for:
Removing project items

Saving documents
Project property editing
Editing the project in an alternate view
Drag-and-drop operations
Drag-and-drop interaction model

Projects typically classify themselves as reference-based (able to persist only references to project items in storage),
directory-based (able to persist only project items physically stored within a project's hierarchy), or mixed (able to persist
references or physical items). The integrated development environment (IDE) accommodates all three types of projects
simultaneously within the Solution Explorer.
From a drag-and-drop perspective, the following characteristics should apply to each type of project within the Solution
Explorer:
Reference-based project: The key point is that the project is dragging around a reference to an item in storage.
When a reference-based project acts as a source for a move operation, it should only remove the reference to the
item from the project. The item should not actually be deleted from the hard drive. When a reference-based
project acts as a target for a move (or copy) operation, it should add a reference to the original source item
without making a private copy of the item.
Directory-based project: From a drag-and-drop point of view, the project is dragging around the physical item
rather than a reference. When a directory-based project acts as a source for a move operation, it should end up
deleting the physical item from the hard drive as well as removing it from the project. When a directory-based
project acts as a target for a move (or copy) operation, it should make a copy of the source item in its target
location.
Mixed-target project: From a drag-and-drop point of view, the behavior of this type of project is based on the
nature of the item being dragged (either a reference to an item in storage or the item itself). The correct behavior
for references and physical items are described above.
If there were only one type of project in the Solution Explorer, then drag-and-drop operations would be straightforward.
Because each project system has the ability to define its own drag-and-drop behavior, certain guidelines (based on the
behavior of drag-and-drop in Windows Explorer) should be followed to ensure a predictable user experience:
An unmodified drag operation in the Solution Explorer (when neither Ctrl nor Shift keys are held down) should
result in a move operation.
Shift-drag operation should also result in a move operation.
Ctrl-drag operation should result in a copy operation.
Reference-based and mixed project systems support the notion of adding a link (or reference) to the source item.
When these projects are the target of a drag-and-drop operation (CTRL + SHIFT is held down), it should result in a
reference to the item being added to the project.
Not all drag-and-drop operations are sensible across combinations of reference-based, directory-based, and mixed
projects. In particular, it is problematic to pretend to allow a move operation between a directory-based source project
and reference-based target project because the source directory-based project will have to delete the source item upon
completion of the move. The target reference-based project would then end up with a reference to a deleted item.
It is also misleading to pretend to allow a copy operation between these types of projects because the target referencebased project should not make an independent copy of the source item. Similarly, Ctrl + Shift dragging to a directorybased target project should not be allowed because a directory-based project is unable to persist references. In cases
where the drag-and-drop operation is not supported, the IDE should disallow the drop and show the user the no-drop
cursor (shown in the pointer table below).
To properly implement drag-and-drop behavior, the source project of the drag needs to communicate its nature (for
example, is it reference- or directory-based?) to the target project. This information is indicated by the clipboard format
that is offered by the source. As the source of a drag (or clipboard copy operation) a project should offer either
CF_VSREFPROJECTITEMS or CF_VSSTGPROJECTITEMS respectively, depending on whether the project is reference-based
or directory-based. Both of these formats have the same data content, which is similar to the Windows CF_HDROP format
except that lists of strings, instead of being filenames, are a double-NULL terminated list of Projref strings (as returned
from IVsSolution::GetProjrefOfItem or ::GetProjrefOfProject as appropriate).
As the target of a drop (or clipboard paste operation), a project should accept both CF_VSREFPROJECTITEMS and
CF_VSSTGPROJECTITEMS, though the exact handling of the drag-and-drop operation varies depending on the nature of
the target project and the source project. The source project declares its nature by whether it offers
CF_VSREFPROJECTITEMS or CF_VSSTGPROJECTITEMS. The target of the drop understands its own nature and thus has
enough information to make decisions as to whether a move, copy, or link should be performed. The user also modifies
which drag-and-drop operation should be performed by pressing the Ctrl, Shift, or both Ctrl and Shift keys. It is important
for the drop target to properly indicate which operation will be performed in advance in its DragEnter and DragOver
methods. The Solution Explorer automatically knows whether the source project and the target project are the same
project.
Drag-and-drop of project items across instances of Visual Studio (for example, dragging from one instance of devenv.exe
to another) is specifically not supported. The Solution Explorer also directly disables this.
The user should always be able to determine the effect of a drag-and-drop operation by selecting an item, dragging it to
the target location, and observing which of the following mouse pointers appears before the item is dropped, as seen in
the following table:
Mouse pointer
Command
Description
No drop
Item cannot be dropped to the specified location.
Copy
Item will be copied to the target location.
Move
Item will be moved to the target location.
Add reference
A reference to the selected item will be added to the target location.

Reference-based projects
The following table summarizes the drag-and-drop (as well as cut/copy/paste) operations that should be performed based
on the nature of the source item and modifier keys pressed for referenced-based target projects:
No modifier
Shift-Drag
Ctrl-Drag
Source item: Reference/Link
Source item: Physical item or file system

(CF_HDROP)
Action
Move
Link
Target
Adds reference to original item
Source
Deletes reference to original item
Retains original item
Result
DROPEFFECT_ MOVE is returned as action from

::Drop; item remains in original location in
storage
DROPEFFECT_LINK is returned as action from

::Drop; item remains in original location in storage
Action
Move
Target
Source
Result

storage.
Action
Copy
Target
Source
Retains reference to original item
Result
DROPEFFECT_ COPY returned as action from

storage.
Action
Link
Link
Target
Source
Result
DROPEFFECT_ LINK returned as action from

storage.
DROPEFFECT_ LINK is returned as action from

storage.
Note
Same behavior as drag-and-drop of shortcut in

Windows Explorer.
Action
Move
Link
Target
Source
Result
Item remains in original location in storage
Action
Copy
Link
Target
Source
Result
Ctrl-Shift-Drag
Cut/Paste
Copy/Paste
No drop
No drop

Directory-based projects
on the nature of the source item and modifier keys pressed for directory-based target projects:
No modifier
Shift-Drag
Ctrl-Drag

(CF_HDROP)
Action
Move
Move
Target
Copies item to target location
Source
Deletes item from original location
Result


::Drop; item is deleted from original location in
storage
Action
Move
Move
Target
Source
Result

storage.

storage
Action
Copy
Copy
Target
Source
Result

storage.

storage.
No drop
No drop
Action
Move
Move
Target
Source
Result
Item is deleted from original location in storage
Action
Copy
Copy
Target
Source
Result
Ctrl-Shift-Drag
Cut/Paste
Copy/Paste

Mixed-target projects
on the nature of the source item and modifier keys pressed for mixed target projects:
No modifier
Shift-Drag
Ctrl-Drag
Ctrl-Shift-Drag
Cut/Paste
Copy/Paste

(CF_HDROP)
Action
Move
Move
Target
Source
Result


storage
Action
Move
Move
Target
Source
Result


storage
Action
Copy
Copy
Target
Source
Result


storage
Action
Link
Link
Target
Adds reference to original source item
Source
Result


storage
Action
Move
Move
Target
Source
Result
Item is deleted from original location in storage
Action
Copy
Copy
Target
Source
Result

These details should be taken into consideration when implementing drag-and-drop in the Solution Explorer:
Design for multiple selection scenarios.

File names (full path) must be unique across the target project or the drop should not be allowed.
Folder names must be unique (case-insensitive) at the level they are being dropped.
There are behavior differences between files that are open or closed at time of drag-and-drop (not mentioned in
scenarios above).
Top-level files behave slightly differently than files in folders.
Another issue to be aware of is how to handle move operations on items that have open designers or editors. The
expected behavior is as follows (this applies to all project types):
1.
2.
If the open editor/designer does not have any unsaved changes, then the editor/designer window should be
silently closed.
If the open editor/designer does have unsaved changes, then the source of the drag should wait for the drop to
occur and then ask the user to save the uncommitted changes in the open documents before closing the window
with a prompt similar to the following:
========================================================
One or more open documents have unsaved changes.
Do you want to save uncommitted changes before proceeding?
[Yes]
[No]
[Cancel]
========================================================
This gives the user the opportunity to save work in progress before the target makes its copies. A new method
IVsHierarchyDropDataSource2::OnBeforeDropNotify has been added to enable this handling.
The target will then copy the state of the item as it is in storage (not including the unsaved changes in the editor if the
user chose No). After the target has completed its copying (in IVsHierarchyDropDataSource::Drop), the source is given
the opportunity to complete the delete portion of the move operation (in IVsHierarchyDropDataSource::OnDropNotify).
Any editors with unsaved changes should be left open. For those documents with unsaved changes, this means that the
copy portion of the move operation will be performed but the delete portion will be aborted. In a multiple selection
scenario when the user chooses No, those documents with unsaved changes should not be closed or removed, but those
without unsaved changes should be closed and removed.

Common control patterns: Common controls

Common controls make up the majority of the user interface in Visual Studio. Most common controls used in the Visual
Studio interface should follow the Windows Desktop interaction guidelines. This document covers special situations or
details that augment those Windows guidelines and are specific to Visual Studio.
Common controls in this topic
Scrollbars
Input fields
Combo boxes and drop-down lists
Check boxes
Radio buttons
Group frames
Common controls in other topics

Search
Text controls
Lists and grids
Tree views
Visual style
The first thing to consider when styling controls is whether the controls will be used in themed UI. Controls in standard UI
are non-themed UI and must follow normal Windows Desktop style, meaning that they are not re-templated and should
appear in their default control appearance.
Standard (utility) dialogs: not themed. Do not re-template. Use basic control style defaults.
Tool windows, document editors, design surfaces and themed dialogs: Use specialized themed appearance
using the color service.
Scrollbars
Scrollbars should follow common interaction patterns for Windows scrollbars unless they are augmented with content
information, such as in the code editor.
Visual style
See Shared colors for scrollbar color tokens. For information on theming scrollbars, see Using themed controls.

Input fields
For typical interaction behavior, follow the Windows Desktop guidelines for text boxes.
Visual style
Input fields should not be styled in utility dialogs. Use the basic style intrinsic to the control.
Themed input fields should only be used in themed dialogs and tool windows.
Specialized interactions
Read-only fields will have a gray (disabled) background but default (active) foreground.
Required fields should have <Required> as watermarks within them. You should not change the color of the
background except in rare situations.
Error validation: See Error validation.
Input fields should be sized to fit the content, not to fit the width of the window in which they are shown, nor to
arbitrarily match the length of a long field, such as a path. Length might be an indication to the user of limitations
as to how many characters are allowed in the field.
Incorrect: it is unlikely that the entry for 'Assembly name' will be this long.
Correct: the 'Assembly name' input field is now a reasonable length.

Combo boxes and drop-down lists

For typical interaction behavior, follow the Windows Desktop guidelines for drop-down lists and combo boxes.
Visual style
In utility dialogs, do not re-template the control. Use the basic style intrinsic to the control.
In themed UI, combo boxes and drop-downs follow the standard theming for the controls.
Layout
Combo boxes and drop-downs should be sized to fit the content, not to fit the width of the window in which they are
shown, nor to arbitrarily match the length of a long field, such as a path.
Incorrect: the drop-down width is too long for the content that will be displayed.
Correct: the drop-down is sized to allow for translation growth, but not unnecessarily long.
Check boxes
For typical interaction behavior, follow the Windows Desktop guidelines for check boxes.
Visual style
In utility dialogs, do not re-template the control. Use the basic style intrinsic to the control.
In themed UI, check boxes follow the standard theming for the controls.
Interaction with a check box must never pop a dialog or navigate to another area.
Align check boxes with the baseline of the first line of text.
Incorrect: the check box is centered on the text.
Correct: the check box is aligned with the first line of the text.
Radio buttons
For typical interaction behavior, follow the Windows Desktop guidelines for radio buttons.
Visual style
In utility dialogs, do not style radio buttons. Use the basic style intrinsic to the control.
It is not necessary to use a group frame to enclose radio choices.
Group frames
For typical interaction behavior, follow the Windows Desktop guidelines for group boxes.
Visual style
In utility dialogs, do not style group frames. Use the basic style intrinsic to the control.
Layout
It is not necessary to use a group frame to enclose radio choices, unless you need to maintain distinction in a tight
layout.
Never use a group frame for a single control.
It is sometimes acceptable to use a horizontal rule instead of a group frame container.

Common control patterns: Search

This topic has been adapted from Alin Constantins blog article.
Visual Studio has a common search control that should be used whenever you are enabling searching the window content.
Examples include Quick Launch and tool windows such as the Toolbox, Solution Explorer, and ErrorList.
The control can be easily reused in your package and added to any piece of UI. In this article, youll learn which interfaces
to implement or call to implement a searchable dialog or tool window, from both native or managed code.
Implementation
In Visual Studio, the common search control is implemented as a WPF control (the
Microsoft.VisualStudio.PlatformUI.SearchControl class). Its data model is set in the DataContext property, and needs to
be a Gel Microsoft.VisualStudio.Shell.Interop.IVsUIDataSource with specific properties and verb names. An example of
such a data source is the Microsoft.VisualStudio.PlatformUI.SearchControlDataSource class.
Use the control through Visual Studio interfaces such as IVsWindowSearch, IVsWindowSearchHost, IVsSearchTask, and
so on. The control will be accessible from native code (via COM), and will let you focus on Search control set up and
performing searches, rather than implementation.
In order to implement a searchable window, the owner needs to implement the IVsWindowSearch interface.
Creating the search host

To set up search, first create a search host. Query the SID_SVsWindowSearchHostFactory service from the shell, and call
the IVsWindowSearchHostFactory.CreateWindowSearchHost() function. Pass in as the first argument an object
identifying the control to be used as the parent for the search control. The type of parentControl argument depends on
the UI technology used in the window, for example FrameworkElement for WPF, ElementHost for WinForms, or an object
implementing IVsUIWin3twoElement/IVsUIWpfElement and returning the parent indirectly via GetHandle() or
GetFrameworkElement() methods.
Once you have the search host, call IVsWindowSearchHost.SetupSearch() and pass in the object implementing
IVsWindowSearch interface. There are a couple of things happening during this call:
1.
2.
3.
4.
5.
The shell creates the SearchControl WPF control child of the parentControl specified during host creation.
The shell creates a settings data source and calls IVsWindowSearch.ProvideSearchSetting. Your window gets a
chance to override the default values and influence the behavior of the search control (for example, set a
determinate progress type, change the search to be instant or on-demand, or disable MRU items and the popup).
The shell calls IVsWindowSearch.ProvideSearchFilters and ProvideSearchOptions to discover the filter and
options that will be shown (if necessary) in the search control popup.
The shell creates the necessary data sources and associates them with the search control.
If the search control uses MRU items, the search control will use the SVsMRUItemsStore to store/retrieve the
items under the IVsWindowSearchHost.Category GUID.

Setting up the search control

As the user types in the search control the default is a delayed search start the search will start and the shell will call
IVsWindowSearch.CreateSearch() function. The shell parses the user input and creates an object implementing the
IVsSearchQuery interface. This allows for consistent parsing of search strings into tokens, and identifying some tokens as
filtering tokens. In response to the CreateSearch() call, the user needs to return an object implementing IVsSearchTask.
The shell will then call IVsSearchTask.Start() from a background thread to perform the actual search job. Should the user
click the X (stop) button while the search is running, the Stop() function will be called on the UI thread on the search task.
Should the user click the X (clear) button after the search completes or is stopped, the shell will call
IVsWindowSearch.ClearSearch().
While the search is running, the search task is supposed to call IVsSearchCallback.ReportProgress() if the search controls
progress type was changed to SPT_DETERMINATE. When the search is complete, call ReportComplete to notify
completion and the number of results found.
When the search is no longer needed, one can call IVsWindowSearchHost.TerminateSearch() for early release of the
resources associated with the control, such as the data sources.
Visual Studio also optimizes for the most common use case. To create a searchable tool window, you dont have to worry
about setting up the search instead, implement the IVsWindowSearch interface on the same class that implements the
tool window pane (IVsWindowPane or IVsUIElementPane), and the shell will take on the burden of setting up the search
and will provide a hosting place for the search control in the tool window frame area. Even more, classes in Managed
Package Framework (MPF) form such as ToolWindow already implement the necessary interfaces. You can make the
search control appear in your window if you override the SearchEnabled property and return true.
Building a Search control in a managed tool window

Visual Studio SDK contains a Walkthrough: Adding Search to a Tool Window article with step-by-step instructions for
using the search control in a managed tool window. The control is hosted by the shell in the tool window frame area, so
you dont need to worry about setting up the search just override the SearchEnabled property. The search control in the
searchable tool window from the article supports most recently used (MRU) items, search filters, and options, and looks
like this:

Using a Search control in a managed dialog

The Example.SearchControlCS.zip sample demonstrates using the search control from a managed dialog. When built, the
samples package adds two items to the Tools menu (Searchable WinForms dialog and Searchable WPF dialog).
Both dialogs set up a search control and implement similar search capabilities, filtering a list of fruits with names read from
resources.
To set up the search, define a container control that will act as the parent for the search control and call
IVsWindowSearchHostFactory.CreateWindowSearchHost with that container. For WinForms, the most natural container
choice type is ElementHost, which ensures WinForms-WPF interoperability. For WPF, pass in any FrameworkElement (for
example, a grid or border) and the search control will be added as a child of that element.
The two searchable dialogs are implemented in SearchableForm.cs and SearchableWpfWindow.xaml.
In this example, there is only one search control per dialog (and, being managed objects, the dialogs are refcounted), so
its easier to implement the IVsWindowSearch interface directly on the dialogs. If more search controls are needed in a
dialog, create separate objects implementing IVsWindowSearch and pass them to IVsWindowSearchHost.SetupSearch
when creating the search controls.
If implementing the same kind of search in both dialogs, its possible to reuse the search task class
SearchableWindowSearchTask. It derives from the VsSearchTask class in MPF and does the real search by overriding the
OnStartSearch method. It compares the typed user strings (from tokens of the search query) with the known fruits read
from resources. The results are added to UI via two callback methods, clearResultsCallback and addResultCallback,
passed in constructor of the search task. This way, the class can be used to report the results in a WinForms ListBox or add
them to an ObservableCollection bound to by the WPF dialogs ListBox.
The OnStopSearch() function on the search task is called by the search control on the UI thread. The base class sets the
TaskStatus to Stopped and reports completion, so there is no need to override this function.
The OnSearchStart() function on the search task is called from background threads. This allows performing the actual
search job asynchronously and youd have to get out of your way to block the UI. The search task uses
ThreadHelper.Generic.BeginInvoke() to call the UI update callbacks. This is because WinForms controls can only be
accessed on the UI thread that created them. Also, ObservableCollections cant be modified from more than one thread.
To make sure the results are not added to the UI by these callbacks after a search is canceled and the task is stopped, the
code needs to recheck the value of TaskStatus on the UI thread before calling the callbacks.
When using the search control in a dialog:
By default, the search control uses a color scheme that follows the active theme in Visual Studio (for example,
Light/Dark). A dialog usually does not follow the theme colors, and to avoid having a black search control in a
light dialog, youd probably want to set the UseDefaultThemeColors property in the data source to False, and
the control will use the default color scheme regardless of the current theme. A Utilities class in the
Microsoft.Internal.VisualStudio.PlatformUI namespace that allows easier interaction with Gel data sources:
Utilities.SetValue(pSearchSettings, SearchSettingsDataSource.PropertyNames.
UseDefaultThemeColors, false)
The search control uses data source properties that allow it to resize between minimum and maximum values
(default 100/400). The controls width will probably not fit the parent containers entire width by default, so
youll need to set a larger ControlMaxWidth value to make sure the control will stretch to all available space
from parent. For example, use the dialogs width:
Utilities.SetValue(pSearchSettings,
SearchSettingsDataSource.PropertyNames.ControlMaxWidth, (uint)this.Width).
Managed vs. native windows

If choosing between managed and native implementation for your search control window, go with managed
implementation. Using the search control from managed code is simpler, as there are more helper functions and classes in
MPF that help with implementation.
The ToolWindowPane class already implements the IVsWindowSearch interface. If your tool window derives from
this, you can make a tool window searchable by overriding SearchEnabled=true.
The VsSearchTask class can be used as a base class for your search task to implement the IVsSearchTask
members and let you focus on the actual search. Derive from it and override OnStartSearch.
Classes like WindowSearchBooleanOption and WindowSearchCommandOption in
Microsoft.VisualStudio.PlatformUI namespace makes defining search options easier, shown in the search
controls popup as checkboxes or links. The WindowSearchOptionEnumerator class can be used to return a Visual
Studio-style enumerator over an IEnumerable list of search options to be easily returned from
IVsWindowSearch.ProvideSearchOptions.
The WindowSearchSimpleFilter class allows implementing a search filter, shown in popup as a button, by
specifying the name and filter field. For more advanced filtering, derive from the WindowSearchCustomFilter
class. The WindowSearchFilterEnumerator class can be used to return a Visual Studio-style enumerator over an
IEnumerable list of search filters to be returned from IVsWindowSearch.ProvideSearchFilters.
Functions like SetValue/GetTypedValue in Microsoft.Internal.VisualStudio.PlatformUI.Utilities class allow
providing a search controls settings in the data source without having to deal with IVsUIObjects.
Another utility class, Microsoft.VisualStudio.PlatformUI.SearchUtilities, has methods for creating search queries
(IVsSearchQuery) or search tokens from strings, parsing search queries into tokens, and so on.
In a native implementation, youd have to deal with all the above yourself. Youd have to create your own COM classes
even for something simple like changing the search controls setting. The examples below feature some sample
implementations for IVsUIObjects, IVsSearchTask, and IVsWindowSearch. If you have to use filters or options, youd have
write your own classes.
In addition, using the search control in a native dialog requires more code to write to ensure Win32-WPF keyboard
interoperability. There are also some bugs (more on this later).
Using a Search control in a native tool window

The Example.SearchControlCpp.zip sample demonstrates using the search control from a native tool window and dialog.
When built, the samples package adds two items to the Tools menu (Searchable Native Dialog and Searchable Native
Tool Window).
The two menu commands display a dialog and a tool window like these:
To use a Win32 window as the search controls parent, pass in an object implementing the IVsUIWin3twoElement
interface and returning the HWND of the parent window from the GetHandle() function. The class CWin32Element does
exactly that. The sample uses a static Win32 control for the search controls parent.
For both dialog and tool window (in SearchControlCppWindowPane and SearchControlCppDialog), the search is set up
from OnInitDialog() function, which is a handler for the dialogs creation message, WM_INITDIALOG.
As mentioned above, there is no help from the native VSL (Visual Studio Template Library in SDK) on dealing with the
search interfaces. The example defines its own COM classes CMyDialogWindowSearch (implementing IVsWindowSearch)
and CMySearchTask (implementing IVsSearchTask). If you need to use filters or options with the search control, youd
also need to create your own classes implementing IVsWindowSearchSimpleFilter, IVsWindowSearchCustomFilter,
IVsWindowSearchBooleanOption, IVsWindowSearchCommandOption, and the enumerators
IVsEnumWindowSearchFilters and IVsEnumWindowSearchOptions.
Also, in providing search control settings (for example, setting the search type to instant search), youd have to pass in
property values, which are objects implementing the IVsUIObject interface. In the sample, Im defining a class
CVsUIBuiltInPropertyValue that can be used to create values for built-in Gel data types (int, strings, booleans, and so on)
and a couple of functions like Gel::CreateBuiltInValue to create such property values.
The two properties mentioned above for using the search control in managed dialogs (UseDefaultThemeColors and
ControlMaxWidth) will need to be set for native dialogs, too. In addition, there are a couple of gotchas for using the
search control in a native dialog:
To ensure the Win32 dialog forwards keyboard input to the WPF control, the HwndSource window created by the
search host, the child of the dialog needs to intercept the WM_GETDLGCODE message and return
DLGC_WANTCHARS | DLGC_WANTTAB | DLGC_WANTARROWS | DLGC_WANTALLKEYS to indicate it wants to
process keyboard input. The SearchControlHostProc is the subclass proc that does this.
To ensure correct tabbing into the search control Im subclassing the static parent of the search control,
intercepting WM_SETFOCUS messages, and forwarding focus activation to the HwndSource child. WPF will
further focus the SearchControl. The SearchControlParentProc is the subclassed window proc of the static
control.
To ensure tabbing out the search control, Im intercepting WM_CHAR(VK_TAB) on the HwndSource and focusing
the next parent dialogs control in tab order.
In future versions of Visual Studio, this might be handled by the shell, but it is currently necessary for the search
implementers to handle it themselves.
There is another problem you might have noticed in the screenshot above: if the height of the parent static control is
bigger than needed by the search control, a black band appears under the search box. The Visual Studio team is aware of
the bug and working to fix it for future releases. As a workaround, set the background brush on the HwndSource at
creation time.
Samples used
Example.TestTool Windowsearch.zip demonstrates using the search control in a managed Toolwindow

Example.SearchControlCS.zip demonstrates using the search control in managed dialogs (WF and WPF)
Example.SearchControlCpp.zip demonstrates using the search control in native dialogs and tool windows

Common control patterns: Text controls

This topic covers appearance, states, and usage of text controls.
Labels
Active label state
Utility (standard) dialogs
In general, follow the Windows Desktop guidance for control labels
In utility dialogs, labels should appear non-bold, in the standard environment font and text color
Ellipses should always follow labels
Disabled label state

Labels should reflect the appearance of the control they are associated with. For example, if the associated control is
disabled, then the label should appear gray and disabled. This is usually handled by the OS and requires no special
treatment.
Dynamic labels
Dynamic labels are those that change based on the current selection. Whenever possible, use dynamic labels in
master/detail layouts to help the user understand that the displayed information is relevant to a specific selection and not
general information.
Here is a common example of a dynamic label used with dynamic content:
Instructional text
Some interface elements benefit from instructional text to help the user understand the UI purpose or to indicate which
action to take.
Instructional text is most common at the top of dialogs, but can appear in other areas to give instruction to a
complex control grouping.
Instructional text is non-interactive, but may contain hyperlinks to Help topics.
Use instructional text sparingly and only when needed.

Formatting
Instructional text should be Environment font, standard (non-themed) control text. For details on writing instructional text,
see UI Text and Help.
Informational text
Informational text is text that gives the user additional information. It may be static or dynamic, or used as a notification. It
is always read-only, but if it is useful for the user to have the ability to copy the information, dynamic text should be
placed in a control container such as a read-only text field.
Dynamic (context-specific) text

Dynamic text is information text that changes depending on context, such as when the user switches focus. Often, but not
always, dynamic content is paired with a dynamic label.
Formatting
There are two ways to display read-only text fields: either directly on the UI surface (see above) or contained within
another control, such as a group frame or text box. Either is correct depending on the situation. It is up to the feature
designer to determine how to present the read-only information.
Text can be inside a read-only text box. This generally indicates that the content can be selected and copied, although it
cannot be edited.

Watermarks
While the wording might be the same, the difference between watermarks and instructional text is that watermarks are
replaced with content when the control/window is not empty, and instructional text remains visible at all times.
Watermarks should be used when a window or control is empty. They indicate what needs to be done to populate the
area and may include action links to open relevant windows, such as a drag source.
Visual style
Centered horizontally within window
Center aligned (not left-aligned)
Position may be vertically centered or positioned near the top of the area. If located at the top of the area, there
must be enough space above so that the watermark stands out.
Use the Environment.GrayText color token and standard environment font. Hyperlinks should use the standard
hyperlink shared tokens: Environment.PanelHyperlink, Environment.PanelHyperlinkHover,
Environment.PanelHyperlinkPressed, and Environment.PanelHyperlinkDisabled.
Watermarks cannot be selected on the background.
If possible, include links in the watermark to help the user get started.
Related topics
Common controls
6: UI Text and Help specifics on language and terminology (the content of the text itself)
8: Layout positioning of text controls in relation to other controls in the UI elements

Common control patterns: Buttons and hyperlinks

Buttons and link controls (hyperlinks) should follow basic Windows Desktop guidance for usage, wording, sizing, and
spacing. Visual Studio has four unique issues related to these controls:
How do I choose between a button or a hyperlink in Visual Studio?
When is it appropriate to theme common buttons in Visual Studio?
What are the special buttons in Visual Studio?
How should I style hyperlinks in Visual Studio?
Choosing between buttons and links

Traditionally, buttons have been used for actions and hyperlinks have been reserved for navigation. Buttons may be used
in all cases, but the role of links has been expanded in Visual Studio so that buttons and links are more interchangeable in
some conditions.
When to use command buttons:
Primary commands
Displaying windows used to gather input or making choices, even if they are secondary commands
Destructive or irreversible actions
Commitment within wizards and page flows
Avoid command buttons in tool windows, or if you need more than two words for the label. Links can have longer labels.
When to use links:
Navigation to another window, document, or web page
Situations that require a longer label or short sentence to describe the intent of the action
Tight spaces where a button would overwhelm the UI, provided that the action is not destructive or irreversible
De-emphasizing secondary commands in situations where there are many commands
Examples
Command links used in the infobar following a status message

Links used in the CodeLens popup
Links used for secondary commands where buttons would call too much attention
Common buttons
Text
Follow the writing guidelines in UI text and terminology.
Visual style
Standard dialogs
Most buttons in Visual Studio will appear in standard dialogs and should not be styled. They should reflect the standard
appearance of buttons as dictated by the operating system.
Themed
In some instances, buttons may be used within styled UI and these buttons must be styled appropriately. See Dialogs:
Themes, and Color value reference for examples and color tokens for common themed controls.
Special buttons
[Browse] buttons are used in grids, dialogs, and tool windows and other modeless UI elements. They display a picker
that assists the user in filling a value into a control. There are two variations of this button, long and short.
The long [Browse...] button
The abbreviated, ellipsis-only [...] button
When to use the ellipsis-only short button:
If there is more than one browse button in a dialog, such as when several fields allow for browsing. Use the short
[...] button for each to avoid the confusing access keys created by this situation (&Browse and B&rowse in the
same dialog).
In a tight dialog or when there is no reasonable place to put the long button.
If the button will appear in a grid control.
Guidelines for using the button:
Do not use an access key. To access it using the keyboard the user must tab from the adjacent control. Ensure that
the tab order is such that any browse button falls immediately after the field that it will fill. Never use an
underscore below the first period.
Set the Microsoft Active Accessibility (MSAA) Name property to Browse... (including the ellipsis) so that screen
readers will read it as "Browse" and not "dot-dot-dot" or "period-period-period". For managed controls, this
means setting the AccessibleName property.
Never use an ellipsis [...] button for anything except a browse action. For example, if you need a [New...] button
but don't have enough room for the text then the dialog needs to be redesigned.
Sizing and spacing

Sizing [Browse] buttons
Spacing [Browse] buttons

Graphical buttons
Some buttons should always use a graphical image and never include text to conserve space and avoid localization
problems. These are often used in field pickers and other sortable lists.
Note: Users have to tab to these buttons (there are no access keys) so place them in a sensible order. Map the name
property of the button to the action that it takes so that screen readers correctly interpret the button action.
Standard buttons
Sizing for graphical buttons is the same as for the short version of the [Browse] button (23x26 pixels):
Appearance of a graphical image on button, with and without transparent color showing
Hyperlinks
Hyperlinks are well suited to navigation-based actions, such as opening a Help topic, modal dialog, or wizard. If a
hyperlink is used for a command, it should always display a visible and noticeable change to the UI. In general, actions that
commit to an action (such as Save, Cancel, and Delete) are better communicated using a button.
Writing style
Follow the Windows Desktop guidance for user interface text. Don't use "Learn more about," "Tell me more about," or
"Get help with this" phrasing. Instead, phrase Help link text in terms of the primary question answered by the Help
content. For example, "How do I add a server to the Server Explorer?"
Visual style
Hyperlinks should always use the VSColor service. If a hyperlink is not styled correctly, it flashes red when active or
shows a different color after being visited.
Do not include underlines at the control resting state unless the link is a sentence fragment within a full sentence,
such as in a watermark.
Underlines should not appear on hover. Instead, the feedback to the user that the link is active is a slight color
change and the appropriate link cursor.

Common control patterns: Lists and grids

Overview
There are four related controls that present data items or groups.
List controls used to present data items or groups in a single dimension, although they can be grouped within
their container
Grid controls used to present data items in tabular form
Tree view controls used to present hierarchical information
Trid (tree-grid hybrid) used to present hierarchical information in tabular form
This topic covers list and grid controls. For information about how hierarchies are presented in tree views, see Tree views.
List controls
Interaction
Icons
Icons should only be used in list controls if they assist in visually identifying differences between the items. Never use
icons in a homogenous list or to represent the shared attribute of items in a heterogeneous list.
Visual style
In a standard (unthemed) dialog, list controls should not be styled .They should reflect the appearance dictated by the
operating system.
Themed style
In tool windows and other themed UI, a grid control must reflect the current Visual Studio theme.
Column headers and column behavior

Column headers should be shown in most cases. Column headers should always be drawn when appearing in a document
window.
Default column width

Size columns to reasonable sizes by default, with the exception of the last column. Do not include an empty column on
the end of the grid to fill up extra space. Either size the last column to fill the rest of the space or, in a dialog, make the
size of the grid control narrower.
Using an empty column to fill space is a Visual Studio anti-pattern.

Hover
In general, grids should follow the standard appearance on hover for the current operating system.
Resize
When resizing a column, no other columns should be affected by the resize operation. This behavior allows the default
sizes of columns to be fixed, and as the user resizes columns, they are not forced to deal with horizontal scrolling.
Moving columns
If useful, column headers should have direct manipulation functionality that lets the user set the order of the columns. The
appearance and behavior of column movement should reflect current Windows behavior for grids. When the mouse is
down during the drag operation, a slight transparency (50% alpha blend) of the column header is shown, moving in the
horizontal plane in the column header channel. A bold, blue vertical bar is shown where the drop will occur. The hit targets
for drop points are to the left and right of the 50% point of each column header (that is, dropping the column to the left
of the 50% point on a column header drops to the left of the column). Upon releasing the mouse, the column is placed at
the location of the bold, blue bar.
Sorting
All list views should support sorting and the list should be sorted by default. The user can sort the list by clicking on a
column header.
Additional UI for setting sort order can be provided through commands or a dialog. The sorted column is indicated by a
small arrow pointing upward for ascending order and downward for descending order. The sort arrow should respond and
scale to changes in the Windows theme.
Once a list is sorted the list should retain that order. If the user chooses another column to sort, the second sort is
performed upon the first sort, and so on. The background of the column that was last sorted is shaded slightly to give
additional feedback.
List body
Data in the list body should be justified according to spreadsheet style rules. Text is left-aligned. Numbers, currency, and
dates are right-aligned within each cell. Sometimes numeric columns are better left-aligned, as in a row of product key
IDs.
Gridlines
Depending on the application, the body of the list may or may not have gridlines. If it is a wide list or many of the cells in
the list are editable, then it might be best to use gridlines. The Visual Studio Task List, for example, has many editable
cells. However, gridlines should not be in lists unless needed to aid the user in finding information.

Row and record selectors

Database development is a common task that spans products and programming languages. The Visual Studio list view
style must allow for the ability to select and edit database-style records.
This kind of editing also applies to XML data. As a result, Visual Studio is consistent with Microsoft Access because of its
widespread acceptance for database development. This standard also allows Microsoft Access developers to scale up to
the database and XML tools in Visual Studio.
Microsoft Access table showing row and record selectors in database UI
When row and record selectors are needed, an additional column is added at the front of the column list. This column
contains row buttons that, when clicked, select the entire row of data. They also serve as a place to draw icons for showing
the editing state of the current row as follows:
Arrow: indicates the current row.

Pencil: indicates data in the row is being edited. If record locks are active, then the pencil means that the row or
record is locked for editing by the current user.
Asterisk: indicates the row where a new record may be added.
Record selectors are the navigation arrows shown at the bottom of the window that hosts the list. These are used for
navigating through the list by going to the first, previous, next, last, and new record. There is a text box between the
record navigation buttons which allows the user to type a record number and go directly to that record. The number of
total records in the set should always be shown. If record selectors are needed, they are embedded alongside the
horizontal scrollbars.

Grouping
The body of a list should simply be a flat list of information, which is why the list control is desirable in certain cases. If the
information you are trying to display is mainly hierarchical, a tree control is a better choice. There are rarer cases in which
long lists of flat information may need to be accompanied by a hierarchical view. There are two types of hierarchical
groupings for lists, categorical and component. Both of these grouping types are used in the Properties window:
Properties window showing categorical and component grouping
Categorical hierarchy is a simple grouping of items in a list. The grouping is shown by a simple label, which has no
functionality other than a place to label and expand or collapse a portion of the list. When a list has a categorical view, the
label is shaded and also creates a hierarchy channel along the left, a place where the Plus and Minus Signs can appear to
expand and collapse the list.
Component hierarchy is used to show that a list item comprises component parts that are also part of the list. In the
example of the Properties window above, the Font property comprises other properties that are also editable.
Scrolling
List columns should be sized to the window width unless the window meets a minimum size. Once the window is below
the horizontal minimum size, the columns should be clipped and a horizontal scroll bar should appear.
The list should not have a scroll bar by default. When the row data grows beyond the window or list container's display
ability (even if a row is partially clipped by the window/container boundary) a vertical scroll bar should appear.
Scroll bars should follow standard Windows behavior and reflect themes. The scroll bar thumbs should be proportional to
the list size.

Implementing list views

Implementing sort arrows
The header uses COLOR_HOTLIGHT to draw the hot divider, when it has the HDS_DRAGDROP style, which the list view
exposes as LVS_EX_HEADERDRAGDROP. You can control it using HDM_SETHOTDIVIDER. You can also use
HDM_CREATEDRAGIMAGE to retrieve the dithered image.
In its simplest form, through managed code you should be able to install an OnPaint event handler for your column
headers and do all of your drawing in the implemented handler.
Dynamically resizing columns on dialog resize

You'll need to come up with an algorithm that meets the requirements for your list box content.In the simplest case, you
could just distribute the columns evenly in the available space. But in most cases, you will want to place priority on a
column and resize around that.
private void OnListViewResize(object sender, EventArgs e)
{
columnHeader1.Width = listView1.Width / 4;
}
Column header sort arrows

Supporting sort arrows in a list view column header in managed code can be problematic, and there is no single managed
solution for displaying sort arrows on a column header. Manipulating a list view's column header requires native
interoperability to achieve the level of control necessary to accomplish this task. Even when using P/Invoke, we cannot use
the facilities provided by ComCtl. List views did not support sort arrows (HDF_SORTDOWN and HDF_SORTUP) until
version 6.0.
There is no great solution. In order to stay consistent, do the following:
1.
2.
3.
4.
Subclass the ListView class.

Draw up and down sort arrows using: font Marlett, size 10.0 pt, color VSCOLOR_GRAYTEXT, values "5" and "6."
Store these in bitmaps in an image list.
Set the ListView column header's ImageList using the SendMessage API with the message LVM_SETIMAGELIST.
Override the OnColumnClick event handler with:
protected override void OnColumnClick(ColumnClickEventArgs e)
5.
Add code to OnColumnClick that will set the appropriate column header's bitmap to be one of the sort arrows.
You can do this using the SendMessage API and the message HDM_SETITEM.

Useful code snippets

[StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode, Pack=4)]
private struct HDITEM
{
public uint mask;
public int cxy;
[MarshalAs(UnmanagedType.LPTStr)]
public string pszText;
public IntPtr hbm;
public int cchTextMax;
public int fmt;
public int lParam;
public int iImage;
public int iOrder;
public uint type;
public IntPtr pvFilter;
}
[DllImport("User32.dll", CharSet=CharSet.Unicode)]
private static extern IntPtr SendMessage(IntPtr hWnd, int msg, int wParam, int
lParam);
[DllImport("User32.dll", CharSet=CharSet.Unicode)]
private static extern IntPtr SendMessage(IntPtr hWnd, int msg, int wParam, ref HDITEM
lParam);

Common control patterns: Tree views

Tree views provide a way to organize complex lists into parent-child groups. A user can expand or collapse parent groups
to reveal or hide underlying child items. Each item within a tree view can be selected to provide further action. This topic
covers acceptable use, proper design, and functionality of tree views.
Visual style
Expanders
Tree view controls should conform to the expander design used by Windows and Visual Studio. Each node uses an
expander control to reveal or hide underlying items. Using an expander control provides consistency for users who might
encounter different tree views within Windows and Visual Studio.
Correct: proper style of tree view node using an expander control.
Incorrect: improper style of tree view node.
Selection
When a node is selected within the tree view, the highlight should expand to the full width of the tree view control. This
helps users clearly identify which item they have selected. Selection colors should reflect the current Visual Studio theme.
See Shared colors for the shared colors you should use to select items within a tree view.
Correct: highlight of the selected node fits the entire width of the tree view control.
Incorrect: highlight of the selected node does not fit the entire width of the tree view control.

Icons
Icons should only be used in tree view controls if they assist in visually identifying differences between items. In general,
icons should be used only in heterogeneous lists in which the Icons carry information to differentiate the types of
elements. In a homogeneous list using icons can frequently be seen as noise and should be avoided. In that case the
group icon (parent) can convey the type of items within it. The exception to this rule would be if the icon is dynamic and is
used to indicate state.
Scroll bars
Scroll bars should always be hidden if the content fits within the tree view control. It is acceptable for scroll bars to be
hidden, or semi-transparent in a scrollable window and appear when the window containing the tree view has focus, or
upon hover of the tree view itself.
Both vertical and horizontal scroll bars are displayed because the contents have exceeded the limits of the tree view control.
Interactions
Context menus
A tree view node can reveal submenu options in a context menu. Typically, this occurs when a user has right-clicked an
item or pressed the Menu key on a Windows keyboard with the item selected. It's important that the node gains focus and
is selected. This helps the user identify which item the submenu belongs to.
The item that has generated the context menu gains focus to notify the user which item has been selected.

Keyboard
The tree view should provide the ability to select items and expand/collapse nodes using the keyboard. This ensures that
navigation meets our accessibility requirements. See Accessibility.
Tree view control

Visual Studio tree controls should follow common keyboard navigation:
Up Arrow: Select items by moving up the tree
Down Arrow: Select items by moving down the tree
Right Arrow: Expand a node in the tree
Left Arrow: Collapse a node in the tree
Enter key: Initiate, load, execute selected item
Trid (tree view and grid view)

A trid control is a complex control which contains a tree view within a grid. Expanding, collapsing, and navigating the tree
should respect the same keyboard commands as a tree view, with the following additions:
Right Arrow: Expand a node. After the node is expanded, it should continue navigating to the nearest column on
the right. Navigation should stop at the end of the row.
Tab: Navigates to the nearest cell on the right. At the end of the row, navigation continues to the next row.
Shift + Tab: Navigates to the nearest cell on the left. At the beginning of the row, navigation continues to the
rightmost cell in the previous row.
A trid control in Visual Studio

Composite patterns: On-object UI and peeking

This topic gives context to peeking, also known as code peek view, a type of on-object UI unique to Visual Studio.
On-object UI should give the user more information or interactivity without detracting from their main task
The main pattern for on-object UI in Visual Studio is known as information at the point of attention
On-object UI in Visual Studio is either inline or floating and either durable or transient
Code peek view, a type of on-object UI in Visual Studio, is inline and durable
CodeLens, a type of on-object UI in Visual Studio, is floating and transient
Understanding how a piece of code works, or finding details about that code, often requires a developer to switch context
and go to other content or another window. These context shifts can be disruptive, because users can lose focus on their
original task if they leave their main window. Furthermore, getting that original context back can be difficult, especially if
switching windows caused their original code to be obscured by other UI.
On-object UI follows a pattern called information at the point of attention. These messages, pop-up windows, and dialog
boxes give users additional, relevant information that adds clarification or interactivity without losing focus on their main
task. Examples of on-object UI include pop-up windows that appear when a user hovers their pointer over an icon in the
notification area, the red squiggle under a misspelled word, and the peek view introduced in Visual Studio 2013.
Decision points
Within Visual Studio, there are several ways to use this pattern of information at the point of attention. Choosing the right
mechanism and implementing it in a consistent, predictable way is essential to the overall experience. Otherwise, users
might be presented with a confusing or inconsistent experience that detracts focus from the content itself.
Relationships between master and detail content

Information at the point of attention is used to display a relationship between content that the user is focused on (the
master content) and additional related content (the detail content). In this pattern, the detail content is clearly related
to the content the user is working with and can be displayed close to the master content. Supplemental information or
information that cannot be summarized without overwhelming the master content should follow another pattern, such as
a tool window.
Always display the detail content in close proximity to the master content.
Always ensure that the detail content still enables a user to remain focused on the master content. Often, the best
way to achieve this is to render the detail content as close to the master content as possible. This can be done by
rendering the detail content in a pop-up window next to the master content, or by rendering the detail content
inline underneath the master content.
Never use information at the point of attention that takes the user away from the master content. If users need to
view the detail content separately, expose an explicit action that enables the user to do this.
Design details
Once you have determined that on-object UI is the right choice, there are four main design considerations:
Persistence: is the content expected to be durable or transient?

Will users want to keep the information visible to refer to or interact with? Or will users want to quickly glance at
the information and then continue with their main task?

Content type: will the content be informational, actionable, or navigational?

Does the user need additional detail about the master content? Does the user need to complete a task that affects
the master content? Or does the user need to be directed to another resource?
Indicator type: does an ambient indicator make sense?

Can the information be summarized in a useful way and displayed without overwhelming the master content?
Gestures: what gestures will be used to invoke and dismiss the UI?
How will the user bring up the detail content and send it away? Is there value in adding a gesture such as pinning
to switch between transient and durable states?
Each of these four decision points will have an impact on the major components of on-object UI.
On-object UI components
1.
2.
3.
4.
5.
Container (content presenter) type

o
Floating
Inline
Content type
o
Informational: data that might be static or dynamic
Actionable: commands that change the master content
Navigational: links that take the user to another window or application, such as to MSDN
Gestures
o
Invocation
Dismissal
Pinning
Other interactions
Persistence and commit model

o
Transient
Durable
Automatic
On-demand
Ambient indicators (optional)

o
Squiggle underline
Smart tag icon
Other ambient indicators
Container (content presenter) type

There are two major options available to present content at the point of attention:
1.
Inline: an inline presenter, such as the peek view that was introduced in the Visual Studio 2013 Code Editor, makes
space for new content by shifting existing content.
o
Prefer inline presenters if you expect users will want to spend a significant amount of time referring to or
interacting with the content you present.
Avoid inline presenters if you expect users will want to glance at the information you present, then
continue with their main task with minimal disruption.
2.
Floating: a floating presenter is positioned as close to the selected content as possible but does not alter the
layout of the existing content. Various strategies can be employed, such as displaying a floating content panel
over the nearest available white space to the selected symbol.

Prefer floating presenters if you expect users will want to glance at the information you present, then
continue with their main task with minimal disruption.
Avoid floating presenters if you expect users will want to spend a significant amount of time referring to
or interacting with the content you present.
Content type
There are three main types of content that can be displayed inside any on-object UI container. Any combination of these
types of information can be shown. The three types are:
1.
Informational: most on-object UI containers will display some kind of informational content. The content can
represent information about the present state of the environment or it may represent information about a
potential future state of the environment. For example, it could be used to show the effect of a particular
command, such as a refactoring, on the existing code.
o
Always use the canonical representation of the information that you display. For example, code should
look like code, complete with syntax highlighting, and should respect whatever font and other
environment settings the user has set.
Always consider supporting any actions over the informational content that would be possible if that
same information is presented as master content. For example, if presenting existing code inside an onobject UI container, strongly consider supporting the ability to browse and modify that code.
Always consider using a different background color if presenting informational content that represents a
potential future state.
2.
Actionable: some on-object UI containers will provide the ability to perform some action over the master content,
such as performing a refactoring operation.
o
Always position actionable commands separately from the informational content.
Always enable and disable actions when appropriate.
Always refer to the standard guidelines for representing commands inside dialog boxes.
Always keep the number of actions that are exposed in an on-object UI container to an absolute
minimum. Interacting with on-object UI should be a lightweight, fast experience. The user should not have
to expend energy on managing the on-object UI container itself.
Always consider how and when an on-object UI container will be closed or dismissed. As a best practice,
any action that concludes the dialog between the master and detail content should also close the onobject UI container when that action is invoked.
3.
Navigational: some on-object UI containers include links that take the user to another window or application,
such as opening an MSDN article in the users web browser.
o
Always prepend any navigational link with Open so that users will not be surprised by being navigated
to some other content.
Always separate navigational links from actionable links.
Ambient indicators (optional)

Ambient indicators can be subtle, including text presented in a contrasting color from the rest of the code, or obvious,
including tickler symbols such as squiggle underlines and smart tag icons. Ambient indicators communicate the availability
of additional, relevant information. Ideally, they provide useful information even without requiring the user to interact with
them.
Always position an ambient indicator so that it does not distract or overwhelm the user. If it is impossible to
position an ambient indicator in such a way, consider another solution.
Always position the ambient indicator as close as possible to the content that its related to.
Always try to create an indicator that summarizes the information it makes available. Consider providing a count
of the number of data items available (for example, 3 references instead of simply References) or think of some
other way to summarize the data.
In cases where the data for an indicator cannot always be computed and displayed, immediately consider
providing progressive feedback as the values are computed. For example, consider animating changes
that reflect updates to the available data, similar to the way the email live tile on Windows Phone
refreshes as the number of unread emails increases.
Never add more indicators than a user can reasonably take in for a given piece of content. Ambient indicators
should be useful without requiring any interaction from the user. Indicators lose their ambience if they require
overflow and other management controls to bring them into view.
Gestures
A key aspect of allowing the user to maintain focus on the master content is by supporting the right gestures to open and
dismiss the additional detail content.
Always require the user to perform some explicit gesture to open the additional content. Common open gestures
include:
o
Hover: tooltips or non-interactive informational content
Explicit command: inline presenter
Double-click the ambient indicator: CodeLens pop-up window
Always dismiss the detail content whenever the user presses the Esc key.
Always consider the context of the on-object UI. For content presenters that allow for interaction within the
container, carefully consider whether to show additional information on hover, which is likely to be disruptive to
the users workflow.
Never display content on hover that appears to be editable or invites user interaction. This behavior can frustrate
users if they try to move the cursor over the detail content, as the standard behavior for a tooltip is to immediately
dismiss when the cursor is no longer over the master content that produced it.

Composite patterns: Selection models

A selection model is the mechanism used to indicate and confirm operations on one or more objects of interest within the
user interface. This topic discusses selection interaction patterns within Visual Studio document editors: text editors,
design surfaces, and modeling surfaces.
Users must have a way of indicating to Visual Studio what they are working on, and Visual Studio must respond
predictably with feedback to users about what it is operating on. Differences or a miscommunication between the user
and the user interface can result in the user not noticing an action, which can have unintended consequences. Often, the
error goes unnoticed until the user sees that something is missing or has changed. Selection models are therefore one of
the most critical pieces of user interface design. Although selection models in Visual Studio are consistent with Windows,
there are slight variations.
In Visual Studio, as in Windows, selection models differ depending on the context in which the interaction occurs.
Selections can occur in four types of objects:
Text
Graphical objects
Lists and trees
Grids
Within these objects, there are three types of selections:
Contiguous
Disjoint
Region
Scope
The most important component of selection is ensuring that the user knows in which window they are working (activation)
and where the focus is located (selection). Visual Studio extends the window management functionality in Windows, but
the activation scheme is the same: interacting with a window brings focus to the window. Visual Studio has two indicators
for activation: one for document windows, and one for tool windows.
For document windows, the active window is indicated by a document window tab coming to the front and changing its
background color, as shown below:
Active window, indicated by a tab and color change

For tool windows, the active window is indicated by a change in the color of the title bar area of the tool window:
Active tool window, showing primary selection of a node
Inactive tool window, showing latent selection of a node
Once a window is active, its focus is indicated according to the selection models outlined in this section of the guidelines.
Context
Visual Studio was designed to retain a strong concept of context, keeping track of where the user is working. Only one
window is active, whether it is a tool or document window. However, the topmost document window always retains a
latent selection. Although the focus might be in a tool window, the document window that was last active displays a
selection, even in an inactive state. This is done to retain the user's context in the document they were editing, showing
them that Visual Studio has retained their state so that they can return and shift seamlessly between tool windows and
document windows.
Text selection
Visual Studio editors that are strictly textual, such as the built-in text editor, use the same text selection model and
appearance described in the Mouse and Pointers page of the Windows User Experience Interaction Guidelines on MSDN.
The input focus in the text editor is indicated by a vertical bar called the insertion point. The insertion point is a single pixel
thick and colored as the inverse of whatever appears behind it. It blinks according to the rate set by the Cursor blink rate
setting in the Speed tab of the Keyboard applet in Control Panel.
Contiguous and disjoint selection

Selection within the text editor is contiguous only. Disjoint text selections are not permitted, but should be addressed in
graphical object editors. When the user's mouse pointer is over a text area, the cursor changes to an I-beam. A single click
places the insertion point in the text editor at the click location. Holding the mouse button down starts a selection
highlight and releasing the mouse button ends the selection highlight.

Region selection (box selection)

Visual Studio supports region selections in the text editor, and this is called box selection. Box selection allows the user to
select a region of text that does not follow the regular text stream. As with standard text selection, the selection must be
contiguous. Box selection is initiated by holding down the Alt key while dragging with the mouse. Box selection can also
be initiated by holding down the Alt and Shift keys while using the arrow keys to indicate the region of selection. Box
selection uses the normal selection highlight and shows the insertion point cursor blinking at the end of the selection area.
Text selection appearance

The colors used for active and inactive selection in the editor can be customized. To customize the visual appearance of
the editor, a user can go to Tools > Options, and then look under Environment > Fonts and Colors > Text Editor.
Graphical selection
Interaction
Graphical object selection can be complex and depends upon a number of factors:
The editor's primary selection model. Editors that contain graphical objects can also be used to edit text or grids.
For example, the editor might be a text-based editor that also supports the placement of graphical objects, such
as the Visual Studio XAML designer. Supporting multiple object types can affect how the user selects groups
made up of different types of objects.
Support for primary and secondary selection states. An editor can provide primary and secondary selection
states so that objects can be edited in unison, aligned with each other, resized together, and so on.
In-place editing support. Editors can also allow the contents of their graphical objects to be edited. For example,
a rectangle shape might also contain text on the inside that can be changed by the user. In addition, that text
could be centered or justified. In-place editing involves a more detailed level of user interaction and therefore
requires an appropriate set of visual cues for presenting state information to the user.

Mouse interaction
Input
Result
Click an unselected object
Selects the object and displays a dashed line and selection handles, if the object is resizable.
Click a selected object

Double-click an object
Point to an object
Activates in-place editing if the object supports it. Clicking outside the object deactivates the inplace editing mode.
Opens the code behind the object for editing, and might insert a default event handler, if
appropriate.
Changes the pointer to the move cursor. The objects appearance, such as its luminosity or
color, might change.
Changes the pointer to the resize cursor. For objects that support rotation, some selection
Point to a selection handle
handles might change the pointer to a rotate cursor as the pointer is positioned differently (for
example, moved farther away) with respect to the selection handle.
Drag
Editor loses focus
Object selection
Even if the object is not previously selected, changes the pointer to the move cursor and moves
the object.
Deactivates in-place editing mode, although the object retains the content and appearance it
had during its last operation/selection state.
Indicated by a border, dotted line, or other visually distinct treatment to highlight the boundary
of the object.
Resize a selected object
Indicated by selection handles.

A resizable object has eight handles, representing each direction in which it can be resized.
Fewer handles may be used if the object can only be resized in certain directions. When the user
sizes an object down to where eight handles would not be interactive, then four handles may be
used. Handle sizes should be tied to the window border and edge metrics with the
GetSystemMetrics API function to size in proportion to the display resolution.
Rotate a selected object

Keyboard interaction
Input
Result
Tab
Moves the focus indicator among the logical order of objects in the editor. This may be leftto-right or top-to-bottom depending on TabIndex (or equivalent) property value, order of
object creation, and the overall purpose of the editor. Shift + Tab reverses the direction of
the focus indicator.
Spacebar
Activates panning mode while keystroke is maintained. Additional mouse input is required
to pan the viewport position.
Ctrl + Spacebar
Activates zoom mode while keystroke is maintained. Additional mouse input is required to
increase and decrease the zoom factor.
Ctrl + Alt + Minus Sign
Decreases the zoom factor by one level.
Ctrl + Alt + Equals Sign
Increases the zoom factor by one level.
Shift OR Ctrl
Adds the object to the selection group. Ctrl also allows you to remove objects individually
from the selection group.
Enter
Performs the default command for the object (usually open or edit).
F2
Activates in-place editing for the object.
Arrow keys
Moves the selected object(s) in the direction of the arrow key pressed, in small increments
(for example, 1 pixel at a time).
Ctrl + arrow keys
Moves the selected object(s) in the direction of the arrow key pressed, in larger increments
(for example, 10 pixels at a time).
Shift + arrow keys
Resizes the selected objects in the respective direction, in small increments (for example, 1
pixel at a time).
Ctrl + Shift + arrow keys
Resizes the selected objects in the respective direction, in larger increments (for example, 10
pixels at a time).
When users edit controls in place, it might make sense for objects to automatically resize with user input. For example, if
the user edits a label control, then the label should grow to display the text that the user just typed. If this is not done, the
user must resize the control manually after editing the text. If the user has a lot of controls, this becomes a rote and
unproductive task.

Graphical containers
In some cases, graphical editors provide containers for other graphical objects, such as the Windows Forms Panel control
or the Grid Layout control in the HTML designer. If your editor provides containers for other graphical objects, then the
following selection model should be used for the container only (objects within the container follow the standard model
as described above):
Input
Result
Single-click on the container
Selects the container object without directly selecting any of the contained objects. The
container may be moved and/or resized with standard mouse and keyboard input (as
described above). Contained objects are moved in relation to the container, but
contained objects are not resized unless they are also directly selected.
Hover over the container's boundary region
Turns the mouse into the move cursor, indicating that the container can be moved.
Drag the container's boundary region
Changes the mouse to the move cursor and moves the container (and the contained
objects within). The container cannot be moved without first being selected with a
single click.
Single-click on an object within the
Deselects the container (if selected) and selects only the clicked object.
container
Shift OR Ctrl + click on a contained object
Adds the clicked object to an existing selection or selection group. If the clicked object
and/or container
is already a member of the selection group, it is removed from the selection group.
The contained objects should adhere to the basic selection model as described in the previous section. From usability
testing of the Windows Forms designer, users expected seamless access to the contained objects without intervening
steps (imposed by the containment object).

Disjoint and region selections

Graphical object editors should support disjoint selections. Please note that this graphic does not show the control
appearance for Visual Studio. See the Graphical object selection appearance section below for detailed visual
specifications.
Disjoint selection
Graphical editors should also provide region selections with a marquee-type selection indicator. If the graphical editor
supports other object types (such as text), then region selections might not be possible depending on the constraints of
those other object types.
Marquee selection indicator
Primary and secondary selections

Some graphical object editors allow the user to edit or align objects in groups. In this case, the concept of primary and
secondary selections needs to be introduced. The primary selection is the object to which all other objects respond for
group operations. The object that the user selects first becomes the primary control, and subsequent selections become
the secondary selections. The primary selection has a distinct visual treatment from the secondary selection(s) to indicate
which object is primary:
A primary selection with two secondary selections

Graphical object selection appearance

The selection handles are squares drawn in a rectangular pattern around the bounding box of the object. The chart below
shows examples of the various states that a graphical object can have with handle, sizing, and in-place editing appearance.
The size of the handles should be tied to window border and edge metrics using the GetSystemMetrics API.
State
Appearance
Visual details
Unselected default state
Resizable
Primary selection
Non-resizable
Locked
Resizable
Secondary selection
Non-resizable
Locked
UI active

View selection models

Tree view
Selection in a tree view is shown with a simple highlight. If the user clicks on a node name or a node icon, the node
becomes selected. The triangular glyphs to the left of the node expand or contract the tree control but do not affect the
user's selection, with one exception: upon collapsing a parent node when the selection is on a child of that node, the
selection moves to the parent.
A typical tree view.
Tree views can support contiguous and disjoint selections, even across multiple levels in the tree. Contiguous or disjoint
multiple selections must be made on visible tree nodes. If a node is collapsed, the disjoint selection is lost and the node
that was collapsed obtains the selection. In this way, the user can see the nodes that will be affected by an operation.
When nodes are collapsed, it becomes unclear which nodes might be affected.
When a parent node is selected, the operation should apply to the parent, though there may be cases where it makes
sense for an operation to apply to the parent and all of its children. In this case, provide additional UI during the
operation, such as a check box or confirmation dialog to make the "apply to all children" option explicit to the user.
Renaming
If nodes in the tree support renaming, renaming should be done in place. The in-place operation should be the standard
across all tree controls in Visual Studio. Provide a rename command that immediately activates the in-place editing mode,
with the text selection covering the entire name of the node, ready to accept user input. If the node represents a file, the
filename should contain the extension. The selection highlight should include only the body of the filename and not the
extension.
Input
Result
Enter key
Commits the rename operation
Esc key
Cancels the rename operation
Clicking outside the in-place edit

region
Commits the rename operation
Undo
Provide easy undo to cancel the rename operation

Selection within lists and grid controls

The key concept in list selection is that it is row-based, meaning that when a selection is made the whole row is selected as
a unit. By contrast, grids can allow specific cells to be selected without affecting any other aspect of the row. Grids might
also contain a hierarchy of nested rows (such as in a TreeGrid) that allow entire branches of the hierarchy to be selected
and deselected by interacting with the parent rows. Selection in lists is shown by a simple highlight color on the entire row
of data. Focus is shown by a single-pixel dotted border around the current editable row or cell (row if all cells are readonly). Note that focus and selection are different concepts. Focus is an indication of which UI element is targeted to receive
input not explicitly directed at another object, while selection refers to the state of an objects inclusion in a set of objects
on which subsequent operations may take place.
Selections in lists may be contiguous, disjoint, or region. When multiple selections are allowed, contiguous and disjoint
selection should always be supported, while support for region (box) selections is optional. Region selections are initiated
by dragging in the white space of the list body.
Object
Selection
List
Contiguous
Always supported (when multiple selections are allowed)
Disjoint
Always supported (when multiple selections are allowed)
Region
Optional support
Initiated by dragging the mouse in the white space of the list body
Grid
Clicking once on a list selects the row where the click occurred. If the user happens to click in a list cell that supports inplace editing, the cell is also immediately activated for in-place editing. Otherwise, the whole row is immediately selected
and shows a highlight.
Dragging in the list body does one of three things:
Initiates a region selection if the list supports it and the mouse-down is in white space.
Initiates a drag/drop operation if the list cell or row supports being a drag source.
Selects the current row.
In-place editing
When in-place editing is allowed, there are two basic models: simple edit control and property picker. With a simple edit
control, the content is highlighted and ready for user input as soon as in-place editing is activated. Where a property
picker is implemented, the button that invokes the property picker is displayed once in-place editing mode is activated,
and the current selection is not highlighted. The picker button should be right-justified in the cell. For in-place editing
examples, see the Properties Window and Task List in Visual Studio.
Keyboard support
Keyboard support for selection in lists and grids follows the standard Windows conventions:
Arrow keys navigate the list, selecting each row/cell as the focus is moved.
Shift + arrow performs a contiguous selection in the direction of the arrow keys.
Ctrl + arrow followed by Spacebar toggles between adding and removing list items from the selection, creating a
disjoint selection.
For grids that contain nested hierarchies, the Right Arrow key expands a parent row, and the Left Arrow key
collapses one.
The Tab key moves focus among the cells in the current row if the cells are editable.
The Enter key performs the default command on the item in the list (often Open).
The F2 key activates in-place editing for the currently selected cell.

Composite patterns: Persistence and saving settings

Although each software component in Visual Studio is usually responsible for its own state and persistence, Visual Studio
automatically saves settings in some cases, such as with window sizes and positions. The table below is a combination of
settings saved automatically and settings that require an explicit user or programmed action to be taken.
Object
What to save
When to save
Where to save it
Selectable object
A breakpoint on a line of code

A user shortcut associated with
the line of code
When the project is saved
The user options (.suo) file for

the project
The location of the dialog, if it

had been moved
The view that the user last used
in the dialog
When the dialog closes

When the Visual Studio session
ends
In memory
Registry in HKEY_Current_User
The size and location of the

window
When the window closes

When the Visual Studio mode
changes (design/debug mode)
ends

the solution
Custom options file for window
settings
When the document is saved

the project
Document
The current selection in the

document
The view of the document
The last several places the user
visited
When the project is saved
The project file
Project
References to files
References to directories on
disk
References to other software
Components
State information about the
project itself
Solution
References to projects
References to files
When the project or solution is

saved
The solution (.sln) file
Keyboard customizations
Toolbar customizations
Color schemes
When the Tools/Options dialog

closes
ends
Registry in HKEY_Current_User
Setting in
(for example, a line

of code)
Dialog
Window
Tools/Options
What the user is doing, and when they are doing it, dictates whether a setting is being saved in memory (during the
session), saved to disk (across sessions as a registry setting), as part of the project or solution file itself, as a part of the
solution options (.suo) file, or as a custom settings file that only that software component knows about. The table above
shows several events at which settings can be saved. However, there are other times in which you might want to save
state:
When the user changes location within a dialog or window

When the user transfers focus to another window
When the user switches from design to debug mode
When the user logs off their account
When the computer goes into hibernation or shuts down
When the computer/hard drive is about to be reformatted and set up again
Window configurations
A window configuration is the basic presentation of the development environment it is a scheme consisting of the list of
tool windows present and the way in which they are arranged. For windows managed by the IDE (IDE windows), layout
information is persisted per user, so when a user launches the IDE, the window layout appears the same as when they last
exited Visual Studio. The state and position of IDE windows is persisted in a custom options file in XML format. Tool
windows that are created by packages loaded into the IDE persist their state information in the registry and may or may
not be per user.
Profile-specific layouts
Each profile includes tool window layouts, organized in a manner familiar to specific developer personas (Visual C++
developers expect to see the Solution Explorer on the left side of the IDE, while C# developers expect to see the Solution
Explorer on the right). Profile-specific window layouts are loaded after the user chooses a profile on startup. A package
author should determine the window layout most suitable for their customer's experience, knowing that changes that the
user makes to the window configuration will then be persisted.

Composite patterns: Touch input

Users are increasingly using Microsoft development products on touch devices. However, there are barriers that make it
difficult to use development tools on touch devices. Users will expect our products to provide a reliable and precise touch
experience. The intent of these guidelines is to inform decisions about which touch capabilities to incorporate and to
encourage a consistent touch experience across Visual Studio and related products.
Levels of experience
The following levels of experience are intended to serve as a guide to help teams decide on which touch capabilities to
offer based on their desired level of investment interest in touch.
The basic experience is for teams that want to provide touch capabilities so there are no dead ends throughout their
application.
The optimized experience is for teams that want to provide the most common touch capabilities (for example, those
typically available in internet browser applications).
The elevated experience is for teams that want to add capabilities such as gestures or other optional capabilities that can
make their application touch-first friendly.
Enables users to
Basic experience
Optimized experience
Elevated experience
Fix code and solution/project-
Perform maintenance, refactors,
Operate in a consistent,
level reading without dead
and navigation tasks
intuitive, and fluid experience
ends
with confidence
Pinch zoom
Fast scroll
Selection
Easy use of context menu
Editor
Touch panning and selection

Scrollbar touch to jump and
press+drag
Top tool windows
List panning
Item selection
Scrollbar touch to jump and
press+drag
Easy item scrolling and selection
Windowing
Resize window
Quick access
Document well
Easy navigation between open

files
Gestures
Ensure common gestures work

across the IDE
Other considerations
Gesture based actions

Support drag n drop in
designers
Custom on-screen keyboard
Gestures
Gestures provide users a shortcut to commands that might otherwise require a more complicated interaction. Refer to the
Windows guidelines on common touch gestures for Desktop Applications, and follow this guidance for most gestures,
including simple gestures such as panning and zooming.

8: Layout

2015 RC PREVIEW
Layout: Dialog layout

The majority of Visual Studio dialogs are utility dialogs, which are the unthemed dialogs that follow standard Windows
Desktop dialog layout principles. As Visual Studio moves to refresh its UI, some of the more prominent dialogs have a new
design that establishes them as product-defining experiences. These signature dialogs have a themed appearance.
Utility dialog layout

General guidance
All controls within a utility dialog should start at the top/left and flow downward.
Never center controls on a dialog to fill a large area.
Use the environment font for all dialog text. When writing a visual spec, specify the environment font instead of
selecting a particular font and size. See The environment font.
Use consistent control spacing and placement to support the goal for quality in craftsmanship.
Dialogs can become more complex from a larger number of controls, a unique juxtaposition of controls, or both.
For those complex situations, allow adequate space between control groupings to give the user a logical flow to
parse.
Utility dialog layout examples

All dimensions are expressed as pixels.
Spacing guidelines for utility dialogs with labels above controls
248 Visual Studio UX Guidelines: Layout

Spacing guidelines for utility dialogs with labels to the left of controls
Visual Studio UX Guidelines: Layout 249

Layout details
Margins
All dialogs should have a 12-pixel border around all edges. Margins within a group frame should be 9 pixels from
the edge of the frame.
Margins within a tab control should be 6 pixels from the edge of the tab control.
Command buttons
Command buttons operate on the dialog frame, not on the content. They should be placed at the bottom right
and should have enough variable space above to set the buttons distinctly separate.
If there are horizontal buttons that operate within the dialog, the alternate command button configuration is a
vertical stack at the upper right.
The space to the left of the command buttons (lower left/center of the dialog) is considered part of the band of
dialog operation controls. The only thing that should intrude on that space is a Help link that is relevant to the
overall task or dialog.
Command buttons should be 75x23 pixels.
Command buttons should be 6 pixels apart.
Basic button alignment
Labels
Left-align all labels.
For labels that sit above a control, they should left-align precisely with the control below it and the bottom of the
label should be 5 pixels above the top of the other control (for example, a combo box).
For labels that sit to the left of controls, the minimum width between the label and the input control is 10 pixels.
An implied second column should be established for aligning the text boxes, combo boxes, or other controls.
Labels are sentence case and are followed by a colon. See 2: Fonts and Formatting > Text style.

Distance between controls

Stack controls reasonably. There is no absolute guideline for the spacing between stacked controls. The tightness between
the controls may vary slightly between dialogs. The recommended spacing is 20 pixels for vertical control/label pairs, and
9 pixels for horizontal control/label pairs. The minimum control spacing for horizontal pairs is 6 pixels.
Recommendations for distance between controls
Control indentation
When controls are nested, align inner controls horizontally with the left edge of the control above, usually the label.
Nested control alignment

Control width
The width of a text box or other similar controls should be no longer than the average input for the field. The average
English word is five characters. For example, a text box that requires a long path name should be as long as the horizontal
layout allows, while a dropdown for platform names should only be a length that allows for the longest entry.
Helper text
A dialog can display helper text that provides more information about the purpose of the dialog. This typically sits
at the top and can be 1-2 sentences.
The line length should be a comfortable width for a user to parse and read. A medium dialog should be no more
than 550 pixels wide.
Interior command buttons

In more complex dialogs, an internal control might have its own related buttons, which might affect where the dialogs
commit buttons are located.
Use a vertical alignment (column) of interior buttons when OK/Cancel are horizontally oriented in the lower right
corner.
Use a horizontal alignment (row) of interior buttons when OK/Cancel are vertically oriented in the upper right
corner. This situation is less common.
Interior button size should target the standard button size of 75x23 pixels, matching the size of OK/Cancel
buttons when possible. If a button label makes the button exceed the standard button size, the other buttons in
that set should align with that wider size.
Vertical interior buttons with horizontal OK/Cancel

Horizontal interior buttons with vertical OK/Cancel
Browse button
[Browse] buttons that follow a text box should spell out "Browse" in full, including the ellipsis. If space is tight or there
are multiple Browse buttons on the screen, the button can be reduced to just the ellipsis. See Buttons and hyperlinks.
Themed dialog layout

Themed dialogs in Visual Studio have a lighter appearance and offer more white space. Typography provides more
emphasis and interest, offering more open line spacing and a variation of font sizes and weights. Where possible, chrome
and title bars have been reduced or removed. The layout of these dialogs should follow this basic pattern:
The background of the dialog is white.
There is a 1-pixel rule border in a mid-value gray.
The dialog title no longer sits in a title bar, but provides visual interest and emphasis in a larger point size. (See the
font size section in Text style).
Labels coupled with additional text, such as a description, should be Environment font + Bold.
Interior columns are separated by a 1-pixel rule in light gray.
Default links have no underscore. Hover and pressed states have a color change plus underscore.
Commit buttons (like OK/Cancel) sit in the lower right corner.

Themed dialog layout examples
Themed dialog

Themed dialog Dimensions

Themed dialog Fonts

Themed dialog Colors

9: Notifications and Progress

2015 RC PREVIEW
Notifications and Progress: Notification systems

There are several ways to inform the user what is happening in Visual Studio regarding their software development tasks.
When implementing any kind of notification:
Keep the number of notifications to the minimum effective number. Notification messages should apply to a
majority of Visual Studio users or to users of a specific feature/feature area. Excessive use of notifications might
sidetrack the user or diminish perceived ease of use of the system.
Ensure you are presenting clear, actionable messages that the user can use to invoke the appropriate context for
making more complex choices and taking further action.
Present synchronous and asynchronous messages appropriately. Synchronous notifications indicate that
something needs immediate attention, such as when a web service crashes or a code exception is thrown. The
user should be informed of those situations right away in a manner that requires their input, such as in a modal
dialog. Asynchronous notifications are ones that the user should know about but not be required to act upon
immediately, such as when a build operation completes or a web site deployment finishes. Those messages
should be more ambient and not interrupt the users task flow.
Use modal dialogs only when necessary to prevent the user from taking further action before acknowledging
the message or making a decision presented in the dialog.
Remove ambient notifications when they are no longer valid. Do not require the user to dismiss a notification if
they have already taken action to address the issue they were notified about.
Be aware that notifications can lead to false correlations. Users might believe that one or more of their actions
has triggered a notification when in fact there was no causal relationship. Be clear in the notification message
about the context, the trigger, and the source of the notification.
Choosing the right method

Use this table to assist you in choosing the right method to notify the user of your message.
Method
Use
Do not use
Modal error message dialogs
Use when a user response is required before
Do not use when there is no need to block the
proceeding.
user and interrupt their flow. Avoid using

modal dialogs if it is possible to show the
message in another, less intrusive way.
IDE status bar

Embedded infobar
Use when there is ambient textual information
Do not use alone. Best used in conjunction
regarding the status of a process.
with another feedback mechanism.
Use in a tool window or document window to
Do not use if the information is not
notify of progress, error state, results, and/or
relevant to the location where the infobar
actionable information.
is placed.
Do not use outside a document/tool

window.
Cursor changes
Use to notify that a process is taking
Do not use for short progress changes or if
place.
fluttering of the cursor is likely (for example,
Use to notify that there is a state change
when tied to parts of a longer running process
in the mouse, such as when drag/drop is
instead of to the entire process).
in progress or that the mouse cursor is in

a certain mode, such as drawing mode.
260 Visual Studio UX Guidelines: Notifications and Progress

Method
Use
Do not use
Progress indicators
Use when you need to report progress (either determinate or indeterminate). There are a
variety of progress indicator types and specific usage for each. See Progress indicators.
Visual Studio Notification window
The Notification window is not publicly
Do not use for other types of notifications.
extensible. However, it is used to communicate

a range of messages about Visual Studio,
including critical issues with your license and
informational notifications of updates to Visual
Studio or to packages.
Error list
1. Use when the issue relates directly to the
Do not use for items that do not have any
user's open solution code, such as an error,
relation to the users open solution code.
warning, or information they might need to

take action on the code.
This would include, for example:
Compiler messages
{error/warning/info}
Code Analyzer/Diagnostic messages

about the code
Build messages
2. Use for issues relating to the project or

solution files, but only after considering a
Solution Explorer indication first.
Editor notifications: Light Bulb
Use when you have a fix available to remedy
Do not use for items that do not have any
an issue that exists in the open file.
relation to the open file.
Note that Light Bulb should also be used for

hosting on-demand Quick Actions on the
user's code, such as refactorings, but in that
case will not appear "notification style."
Editor notifications: Squiggles
Use to alert the user to an issue with a
Do not use for items that do not relate to a
particular span of their open code (for
particular span of their open code.
example, a red squiggle for errors).

Embedded status bars
Use to provide status related to content or
Do not use for general product notifications,
process within context of a specific tool
processes, or items that do not have any
window, document window, or dialog window.
relation to the content within the specific

window.
Windows tray notifications
Use to surface notifications for out-of-proc
Do not use for notifications that are relevant
process or companion applications.
to the IDE, but instead use the Notification

tool window.
Notification bubbles
Use to notify of a remote process or change
Do not use as a means for notifying the user
outside of the IDE.
of processes within the IDE.
Visual Studio UX Guidelines: Notifications and Progress 261

Notification methods
Modal error message dialogs
A modal error message dialog is used to display an error message that requires the user's confirmation or action.
A modal error message dialog alerting the user of an invalid connection string to a database
IDE status bar

The likelihood that users notice status bar text correlates to their all-around computer experience and specific experience
with the Windows platform. The Visual Studio customer base tends to be experienced in both areas, though even
knowledgeable Windows users might miss changes in the status bar. Therefore, the status bar is best used for
informational purposes or as a redundant cue for information presented elsewhere. Any kind of critical information that
the user must resolve immediately should be provided in a dialog or in the Notifications tool window.
The Visual Studio status bar is designed to allow for several types of information to be displayed. It is divided into regions
for feedback, designer, progress bar, animation, and client.
The feedback region and designer region are always visible. The progress bar and animation regions are always dynamic
and based on user context. The designer region has a static width determined by the length of the string that is pulled
from an accompanying resource for the text message. This allows localization to resize the width without requiring a code
change. For English, the width of this string is roughly 220 pixels. The designer region will behave normally and the
feedback region will absorb the remaining space.
The status bar is also colorized to add visual interest and functional value by communicating various IDE state changes
such as when the IDE is in debug mode.
The status bar changes color to show different IDE states.

Embedded infobar
An infobar can be used at the top of a document window or tool window to inform the user of a state or condition. It can
also offer commands so that the user can have a way to easily take action. The infobar is a standard shell control. Avoid
creating your own, which will act and appear inconsistent with others in the IDE. See Infobars for implementation details
and usage guidance.
An infobar embedded in a document window, alerting the user that the IDE is in historical debugging mode and the editor will not
respond in the same way as it does in standard debugging mode.
Mouse cursor changes

When changing the mouse cursor, use colors that are tied to the VSColor service and are already associated with the
cursor. Cursor changes can be used for indicating an ongoing operation, as well as hit zones where the user is hovering
over a target that can be dragged, dropped onto, or used to select an object.
Use the busy/wait mouse cursor only when all available CPU time must be reserved for an operation, preventing the user
from expressing any further input. In most cases with well-written applications using multithreading, times when users are
prevented from doing other operations should be rare.
Keep in mind that cursor changes are useful as a redundant cue for information presented elsewhere. Do not rely on a
cursor change as the sole way of communicating with the user especially when trying to convey something that is critical
that the user must address.

Progress indicators
Progress indicators are important for giving the user feedback during processes that take more than a few seconds to
complete. Progress indicators can be shown in place (near the launching point of the action in progress), in an embedded
status bar, in a modal dialog, or in the Visual Studio status bar. Follow the guidance in Progress indicators regarding their
use and implementation.
Example of a Visual Studio progress indicator, a determinate progress bar
Visual Studio Notifications window

The Visual Studio Notifications window notifies developers about licensing, environment (Visual Studio), extensions, and
updates. It will also help you troubleshoot certain issues you might be experiencing in the IDE. Users can dismiss individual
notifications or can choose to ignore certain types of notifications. The list of ignored notifications is managed in a Tools
> Options page.
The Notifications window is not currently extensible.
The Visual Studio Notifications window

Error list
A notification within the error list indicates errors and warnings that occurred during compilation and/or the build process,
and allows the user to navigate in code to that specific code error.
Error list in Visual Studio
Embedded status bars

Because the IDE status bar is dynamic, with its client region context set to the active document window and information
updating on the user's context and/or system responses, it is difficult to maintain a continuous display of information or
give status on long-term asynchronous processes. For example, the IDE status bar is not appropriate for notifications of
test run results for multiple runs and/or immediately actionable item selections. It is important to retain such status
information in the context of the document or tool window where the user makes a selection or starts a process.
Embedded status bar in Visual Studio

Windows tray notifications

The Windows notification area is next to the system clock on the Windows taskbar. Many utilities and software
components provide icons in this area so that the user can obtain a context menu for system-wide tasks, like changing
screen resolution or obtaining software updates.
Environment-level notifications should be surfaced in the Visual Studio Notifications hub, not the Windows notification
area.
Notification bubbles
Notification bubbles can appear as informational within an editor/designer or as part of the Windows Notification area.
The user perceives these bubbles as issues that they can resolve later, which is a benefit for noncritical notifications.
Bubbles are inappropriate for critical information that the user must solve right away. If you do use notification bubbles in
Visual Studio, follow the Windows desktop guidance for notification bubbles.
Notification bubble indicating a remote process outside of the IDE

Notifications and Progress: Progress indicators

Progress indicators are an important part of a notification system for giving the user feedback. They tell the user when
processes and operations will complete. Familiar indicator types include progress bars, spinning cursors, and animated
icons. The type and placement of a progress indicator depends on the context, including what is being reported and how
long the process or operation will take to complete.
Factors
In order to determine which indicator type is appropriate, you need to determine the following factors.
1. Timing length of time the operation will take
2. Modality whether the operation is modal to the environment (locks the UI until the process is complete)
3. Persistent/Transient whether the final result of the progress needs to be reported and/or viewable at a later
time
4. Determinate/Indeterminate whether the operation end time and progress can be calculated
Graphic/Textual location
6. Proximity whether the progress should be in close proximity to the UI that it is related to. (For example, can it
be in the status bar, which might be far away, or does it have to be near the button that launched the process?)
Decision tree
See next page.


Determinate progress
Progress type
When and how to use
Notes
Progress bar (determinate)
Expected duration of >5 seconds.
DON'T embed text into
May include textual description of process details.
animation.
Messaging associated with contextual UI. See Infobars.
DONT use multiple info bars
when you need to indicate
Infobar
multiple processes (use stacked

progress bars instead).
Output Window
Log file
Transient notification: app-level process that user will want to
DONT use if the user will need
review details of after completion.
to refer to data later.
Paired with intransient notification in cases when it is

important to save details after completion.
Status bar
Transient notification: app-level process that user will not

need details of after completion.
Includes an embedded progress bar.
Indeterminate progress
Progress type
When and how to use
Notes
Progress bar (indeterminate)
Expected duration of >5 seconds.
DON'T embed text into
animation.
Ants
Round trip to server.
DON'T use if not parented by
(animated horizontal dots)
Placed near point of context across top of parent container.
entire container.
Spinner (progress ring)
Process associated with contextual UI, or where space is a

consideration.
Infobar
Messaging associated with contextual UI. See Infobars.
DONT use multiple info bars

when you need to indicate
multiple processes (use stacked
progress bars instead).
Output Window
Log file
Transient notification: app-level process that user will want to
DON'T use for information that
review details of after completion.
needs to persist across sessions.
Paired with intransient notification in cases when it is

important to save details after completion.
Status bar
Transient notification: app-level process that user will not

need details of after completion.
Includes embedded progress bar.

Progress indicator types

Progress bars
Indeterminate
"Indeterminate" means the overall progress of an operation or process cannot be determined. Use indeterminate progress
bars for operations that require an unbounded amount of time or that access an unknown number of objects. Use a
textual description to accompany what is happening. Use timeouts to give bounds to time-based operations.
Indeterminate progress bars use animations to show that progress is being made, but provide no other information. Dont
choose an indeterminate progress bar based only on the possible lack of accuracy alone.
Determinate
"Determinate" means that an operation or process requires a bounded amount of time, even if that amount of time
cannot be accurately predicted. Clearly indicate completion. Dont let a progress bar go to 100 percent unless the
operation has completed. Determinate progress bar animation moves left-to-right from 0 to 100%.
Never move the progress indicator backward during an operation. The bar should move forward steadily when the
operation begins and reach 100% when it ends. The point of the progress bar is to give the user an idea of how long the
entire operation takes, regardless of how many steps are involved.
Concurrent reporting (stacked progress bars)

If an operation will take a long time perhaps several minutes then two progress bars may be used, one that shows
overall progress for an operation and another for the progression of the current step. For example, if a setup program is
copying many files, then one progress bar can be used to indicate how long the entire process takes while a second can
indicate what percentage of the current file or directory is being copied. Do not report more than five concurrent
operations or processes using stacked progress bars. If you have more than five concurrent operations or processes to
report, use a modal dialog with a Cancel button and report the progress details to the Output Window.
Textual descriptions
Use a textual description to accompany what is happening and the estimated time to completion. If it is impossible to
determine how long an operation will take, then a better choice for giving feedback might be an animated icon rather
than a progress bar.
Visual Studio provides a standard progress bar in the status bar that can be used by any product integrated into Visual
Studio. For textual descriptions of what is happening while the progress bar is animated, the status bar text can be
updated.

Other progress indicators

Ants (dots)
"Ants," animated horizontal dots, provide a visual reference for an indeterminate round-trip server process.
Spinner (progress ring)
The spinner (also known as a "progress ring") is an indeterminate progress indicator primarily used in relation to
contextual UI. Display a spinner in close proximity to its related content, such as a textual category header, messaging, or
control.
Cursor feedback
For operations that take between 2-7 seconds, provide cursor feedback. Typically, this means using the wait cursor
provided by the operating system. For guidance, see the MSDN article Cursors.Wait Property.
Progress indicator locations

Status bar
The status bar gives your application a place to display messages and useful information to the user without interrupting
the user's work. Typically displayed at the bottom of a window, status for progress will be a tool tip pane that includes a
message about the measure of progress in combination with a progress bar indicator.
Infobar
Similar to the status bar, the infobar provides contextual notification and messaging, which can also be paired with
indeterminate progress indicators such as the progress bar or spinner. The infobar should not provide granular level
progress or determinate progress indication.

Inline
Inline progress indication can be represented by any of the progress loader types. Typically, the progress indicator is
paired with messaging, but this is not a requirement.
Spinner combined with messaging
Determinate stacked progress bars
Server Explorer inline text (Refreshing)
Server Explorer indeterminate progress bar below title bar and textual process

Dialogs
Dialogs can contain any of the progress loader types. Progress indicators can be paired with messaging as well as
combined with multiple levels of progress indication to represent granular and sub- processes.
A common dialog with concurrent processes and multiple progress indicator types
A dialog with progress loader and messaging inline commanding

Document well
The document well can display multiple progress loader types in combination with controls.
Indeterminate progress bar below toolbar
Output Window
The Output window is appropriate for handling process progression and ongoing progress status via inline textual
messaging. You should use the Status bar along with any Output window progress reporting.
Output window with ongoing process status and wait messaging

Component specification for all bar locations

Components for bar style
When used in a document or tool window, the Bar style has two visual components that change in appearance based on
state, focus, synchronization of progress, and the set color theme. A progress bar comprises a solid 2-pixel-high
background or track color and a solid 2-pixel-high blue fill-in color, as shown here.
Documents have three states: active/in-focus, active/unfocused and inactive. When a document's state changes from one
to another, the color change should be an animated transition.
Progress bar background track

Layout
The visual design is always a 2-pixel solid color static line. In a document window tab, the position and orientation of the
track within a document tab determines the overall placement of the WPF control as a whole. The overall length of the
track runs from the beginning of the left-justified text block in the document tab, to the right edge of the Close button in
the document tab.
In a tool window, the track length snaps to the full width of the window and dynamically adjusts as the windows width
changes.

Status indicators
Layout
Status information will be indicated using the existing Visual Studio tool tip, which appears on MouseOver anywhere over
the progress bar hit target. The dimensions and spacing of the tool tip should be the same as in Dev10.
Motion
The delay time of the fade in/out motion, and the screen position relative to the cursor should be the same as in Dev10.

Progress bar indicator

Layout
The dynamically moving progress indicator will always appear within the progress background track. No outline, chrome,
or shadow gradient will be used in combination with it.
Motion
Use animation to show that a time-consuming operation of a known or unknown length is occurring. In every case, except
for the vertically oriented AutoHideChannel, the blue fill-in color grows in size horizontally from left-to-right. The motion
should feel as smooth as possible while avoiding an intentionally incremental update that would make the motion feel
choppy. Immediately upon activating the progress indication, always show a 5% processed value to provide a visual tick
to indicate activity as well as define the initial location of the progress bar on screen.
1.
Indeterminate
An indeterminate progress bar continuously displays animation indicating that an operation of unknown length is
occurring.
2.
Determinate
Use animation to show that a time-consuming operation of a known length is occurring.

Details
Layout
A progress bar can be used in one several locations simultaneously to represent the in-focus, active state, and visibility of
determinate or indeterminate progress. The following image is an example of the many potential locations that a progress
bar-style control can be considered for use in VSPix for Dev11.
Multiple locations for a bar style indicator. 1) Tab in focus; 2) Tab not in focus; 3) Tool Window;
4) Tool Window Tab not in focus; 5) Inline text
Interaction
A document or tool window has three states: active/in-focus, active/unfocused and inactive. When a document's state
changes from one to another during user interaction, the color should not abruptly shift. Instead, the color change should
be an animated transition.

Notifications and Progress: Infobars

This topic discusses the common controls that create and show an infobar in document and tool windows within Visual
Studio. Infobars give the user an indicator close to their point of attention and using the shared infobar control ensures
consistency in visual appearance and interaction.
Appropriate uses for an infobar
To give the user a non-blocking but important message relevant to the current context.
To indicate that the UI is in a certain state or condition that carries some interaction implications, such as historical
debugging.
To notify the user that the system has detected problems, such as when an extension is causing performance
issues.
To provide the user a way to easily take action, such as when the editor detects that a file has mixed tabs and
spaces.
Do:
Keep the infobar message text short and to the point.
Keep the text on links and buttons succinct.
Ensure the "action" options you provide to users are minimal, showing only required actions.
Don't:
Use an infobar to offer standard commands that should be placed in a toolbar
Use an infobar in place of a modal dialog
Create a floating message outside a window
Use multiple infobars in several locations within the same window.
Can multiple infobars show at the same time?

Yes, multiple infobars can show at the same time. They will be displayed in first-come, first-served order with
the first infobar showing on top and additional infobars showing below.
The user will see a maximum of three infobars at a time, after which, if more infobars are available, the infobar
region will become scrollable.

Creating an infobar
The infobar has four sections, from left to right:
Icon This is where you'd add any icon you'd like to display for the infobar, such as a warning icon.
Text You can add text to describe the scenario/situation user is in, along with links within the text, if required.
Remember to keep the text succinct.
Actions This section should contain links and buttons for actions that the user can take in your infobar.
Close button The last section to the right can have a close button.
Creating a standard infobar in managed code

The InfoBarModel class can be used to create a data source for an infobar. Use one of these four constructors:
public InfoBarModel(IEnumerable<IVsInfoBarTextSpan> textSpans, ImageMoniker image =
default(ImageMoniker), bool isCloseButtonVisible = true);
public InfoBarModel(string text, ImageMoniker image = default(ImageMoniker), bool
isCloseButtonVisible = true);
public InfoBarModel(IEnumerable<IVsInfoBarTextSpan> textSpans,
IEnumerable<IVsInfoBarActionItem> actionItems, ImageMoniker image = default(ImageMoniker),
bool isCloseButtonVisible = true);
public InfoBarModel(string text, IEnumerable<IVsInfoBarActionItem> actionItems, ImageMoniker
image = default(ImageMoniker), bool isCloseButtonVisible = true);
Here is an example that creates an InfoBarModel with some text with a hyperlink, an action button, and an icon.
var infoBar = new InfoBarModel(

textSpans: new[]
{
new InfoBarTextSpan("This is a "),
new InfoBarHyperlink("hyperlink"),
new InfoBarTextSpan(" InfoBar.")
},
actionItems: new[]
{
new InfoBarButton("Click Me")
},
image: KnownMonikers.StatusInformation,
isCloseButtonVisible: true);
Creating a standard infobar in native code

Implement The IVsInfoBar interface in order to provide an infobar from native code.
public interface IVsInfoBar
{
IVsInfoBarActionItemCollection ActionItems { get; }
ImageMoniker Image { get; }
bool IsCloseButtonVisible { get; }
IVsInfoBarTextSpanCollection TextSpans { get; }
}
Getting an infobar UIElement from an infobar

The InfoBarModel or IVsInfoBar implementation are data models that must be turned into a UIElement in order to be
shown in the UI. A UIElement can be retrieved with the SVsInfoBarUIFactory/IVsInfoBarUIFactory service.
private bool TryCreateInfoBarUI(IVsInfoBar infoBar, out IVsInfoBarUIElement uiElement)
{
IVsInfoBarUIFactory infoBarUIFactory =
serviceProvider.GetService(typeof(SVsInfoBarUIFactory)) as IVsInfoBarUIFactory;
if (infoBarUIFactory == null)
{
uiElement = null;
return false;
}
uiElement = infoBarUIFactory.CreateInfoBar(infoBar);
return uiElement != null;
}
Placement
Infobars can be shown in one or more of the following locations:
Tool windows
Within a document tab
It's possible to position an infobar to give a message about global context. This would appear between toolbars
and the document well. This is not recommended because it causes problems with jump and jerk of the IDE and
should be avoided unless absolutely necessary and appropriate.
Placing an infobar in a ToolWindowPane

The ToolWindowPane.AddInfoBar(IVsInfoBar) method can be used to add an infobar to a tool window. This API can either
add an IVsInfoBar (of which InfoBarModel is a default implementation), or an IVsUIElement.
Placing an infobar in a document or non-ToolWindowPane

To place an infobar into any IVsWindowFrame, use the VSFPROPID_InfoBarHost property to get the IVsInfoBarHost for the
frame, and then add the infobar UIElement.
private void AddInfoBar(IVsWindowFrame frame, IVsUIElement uiElement)
{
IVsInfoBarHost infoBarHost;
if (TryGetInfoBarHost(frame, out infoBarHost))
{
infoBarHost.AddInfoBar(uiElement);
}
}
private bool TryGetInfoBarHost(IVsWindowFrame frame, out IVsInfoBarHost infoBarHost)
{
object infoBarHostObj;
if (ErrorHandler.Failed(frame.GetProperty((int)__VSFPROPID7.VSFPROPID_InfoBarHost, out
infoBarHostObj)))
{
infoBarHost = null;
return false;
}
infoBarHost = infoBarHostObj as IVsInfoBarHost;
return infoBarHost != null;
}
Placing an infobar in the main window

To place an infobar in the main window, use the VSSPROPID_MainWindowInfoBarHost of the IVsShell service to get the
main window's IVsInfoBarHost, and then add the infobar UIElement to it.
Will I know when the user takes action in my infobar?

Yes, we will return every event action to the infobar author. It is then up to the infobar author to take action in the IDE
based on user selection in the infobar. Infobars will be automatically removed from the host whose Close button was
clicked, but additional work is required if other infobars need to be removed after close. Telemetry also will need to be
logged independently by each infobar.
Receiving infobar events in a ToolWindowPane

ToolWindowPane has two events for infobars. The InfoBarClosed event is raised when an infobar in the ToolWindowPane
is closed. The InfoBarActionItemClicked event is raised when a hyperlink or button inside the infobar is clicked.
Receiving infobar events directly from the UIElement

IVsInfoBarUIElement.Advise can be used to subscribe to events directly from an infobar's UIElement. Implementing
IVsInfoBarUIEvents will allow the author to receive close and click events.
public interface IVsInfoBarUIEvents
{
void OnActionItemClicked(IVsInfoBarUIElement infoBarUIElement, IVsInfoBarActionItem
actionItem);
void OnClosed(IVsInfoBarUIElement infoBarUIElement);
}
Creating custom infobars

In general, we recommend that you use the standard controls provided for infobars.

Notifications and Progress: Error validation

When a user enters information that is not acceptable, such as when a required field is skipped or when data is entered in
the incorrect format, it is better to use control validation or feedback near the control instead of using a blocking popup
error dialog.
This topic covers three variants of error validation:
Field validation
In-place warning text
Watermarks
Field validation
Form and field validation consists of three components: a control, an icon, and a tooltip. While several types of controls
can use this, a text box will be used as an example.
If the field is required, there should be watermark text stating <Required> and the field background should be light
yellow (Environment.InfoBackground) and the foreground should be gray (Environment.InactiveCaptionText):
The program can determine that the control is in a state of invalid content entered either when focus is moved to another
control or when the user clicks on an [OK] commit button or when the user saves the document/form.
When the invalid content state is determined, an icon appears either inside the control or just beside it. A tooltip
describing the error should appear on hover of either the icon or the control. Additionally, a 1-px border should appear
around the control that is creating the invalid state.

Acceptable variations for icon location

There are countless unique cases in which users need to be informed about validation errors. Choose the placement of the
icon as appropriate to your situation.
Validation requiring a round trip to a server or a network connection

In some cases, a round trip to the server is required to verify the content, and it would be important to show the user
progress, verified, and error states. The below figure shows an example of this case and the recommended UI.
Note that adequate available space to the right of the control must be provided in order to accommodate the
Verifying and Retry text.
In-place warning text

When there is room available to put the error message close to the control in a state of error, this is preferable to using
the tooltip alone.
Watermarks
Sometimes an entire control or window is in an error state. In this situation, use a watermark to indicate the error.

10: HDPI Requirements

2015 RC PREVIEW
HDPI requirements: Supporting HDPI displays

An increasing number of devices are shipping with high-resolution screens. These screens typically have over 200 pixels
per inch (ppi). Examples include the Microsoft Surface Pro, Fujitsu Lifebook, Samsung ATIV Book 9 plus, and Toshiba
KiraBook. Working with a computer on these applications will require content to be scaled up to meet the needs of
viewing the content at a normal viewing distance for the device. As of 2014, the primary target for high-density displays is
mobile computing devices (tablets, clamshell laptops, and phones).
Windows 8.1 and higher contains several features to enable these machines to work with displays and environments
where the machine is attached to both high-density and standard-density displays at the same time.
Windows can allow you to scale content to the device using the Make text and other items larger or smaller
setting (available since Windows XP).
Windows 8.1 and higher will automatically scale content for most applications to be consistent when moved
between displays of differing pixel densities. When the primary display is high density (200% scaling) and then
secondary display is standard density (100%), Windows will automatically scale the application window contents
down on the secondary display (1 pixel displayed for every 4 pixels rendered by the application).
Windows will default to the right scaling for the pixel density and viewing distance for the display (Windows 7 and
higher, OEM-configurable).
Windows can automatically scale content up to 250% on new devices that exceed 280 ppi (as of Windows 8.1
S14).
Note: Some devices are designed as high-density devices, though the Windows scaling features are not universally used:
Asus Zenbook Prime (125% scaling)

Microsoft Surface Pro (150% scaling)
During the next several years, the market is expected to continue to accelerate to require scaling factors up to and
exceeding 400% due to competitive pressure among hardware vendors. Both Windows and the applications and
developer ecosystem that constitute it will need to move to pixel density-agnostic software designs to keep up.
Goal for Microsoft developer tools

The end goal for using Microsofts developer tools on high-density displays is consistency between experiences across
devices. The user should continue to interact with a user interface that is natural and consistent regardless of the pixel
density. Images and text are the right size for the display and clear to see. Default sizes of UI layout for both user interface
assets and customer assets should be consistent with the experience on standard-density displays. Finally, the user must
be able to see all UI and content and complete all tasks as on any other display.
Minimum display requirements

Run test passes through your UI plan, roadmap, and test cases in at least 150%, 200%, and 250% at the minimum
resolution applicable for each scaling factor. For specific information about testing for high-DPI support, see Validating for
high-density displays.
As pixel densities will continue to increase over the next several years, user experiences will degrade when bugs go
unfixed. However, most issues are relatively simple to fix and easy to test, requiring perhaps only minutes to a couple
hours to fix. Dev12 had a very low rate of regressions due to high-density fixes. Fixes and UI that are done correctly will
not have to be addressed again as pixel densities increase.
288 Visual Studio UX Guidelines: HDPI Requirements

Examples of high-DPI bugs

The following are examples of must-fix issues that shipped in Visual Studio 2012 and were fixed in 2013.
Description
Example
Solution
Theres no way to see or
Fix: make grid respect the size
edit the text in the
of the font, not the size of the
debugger windows.
icon.
There is no way for a user

to enter or see pre/postbuild event command
lines in the editor.
Fix: set up layout mode flag
Solution Explorer icons
Fix: enable custom drawing
become difficult to
code to scale icons up.
on controls in WinForms.
discern on a high-density
display.
Visual Studio UX Guidelines: HDPI Requirements 289

Description
Example
Solution
Toolbox icons are
Fix: load and draw icons
difficult to discern on a
larger using the DPI helper
high-density display.
library.
Designer selection icons
Fix: scale the icons up.
are impossible to discern

at 200%.
The binary editor font is
Fix: use the text editor font
much smaller than the
(which is exposed to user
environment font,
customization under Tools >
making text hard to read.
Options > Fonts and

Colors).

HDPI requirements: Validating for HDPI displays

In order to validate that your UI works in high-pixel-density conditions, user interface contributions need to be validated
for new pixel density scaling standards, when platform bugs are addressed, and when new user interface components are
added or changed.
Since the conditions for needing to re-validate your UI are present in nearly every release, teams should plan to do a test
pass on all their UI on high-DPI displays in order to sign off on any release.
Completed user interface components should include human testing on high-density displays to ensure architectural and
layout issues were not missed during the implementation phase of a project. Failure to ensure that the user interface
works on high-pixel-density displays might impede critical feedback from customers even in early releases of the product.
All teams should know what UI components they contribute to the user interface and have a user experience test roadmap
to exercise and discover bugs. Regressions and customer issues should be used to inform and enhance the test pass, to
ensure adequate coverage to exercise end-to-end scenarios and important permutations in the user interface. Pay
attention to the way the UI is rendered, the way user content is laid out, and the way the user accesses the UI through
appropriate keyboard, touch and mouse gestures.
Run test passes through your UI plan, roadmap, and test cases in at least 150%, 200%, and 250% of the minimum
resolution applicable for each scaling factor.
Performance, responsiveness, and stress considerations

Teams should also plan to do performance, responsiveness, and stress validation in their areas if applicable. These criteria
are more likely to be applicable if the fix applies to displaying many images or core algorithms that pertain to images,
resource loading, or UI layout and rendering. Examples include the Solution Explorer, the core DPI library, .NET framework,
or theming services.
The expectation is zero regression on 100%. Small regressions on higher scaling factors can be expected due to increased
memory use, but should not decrease mean time to failure (out of memory failures).

Testing with HDPI displays

Its important to test on real hardware using a real high-density display of the right pixel density. While its possible to
emulate high-pixel counts without a high-density display, testing without using a high-density display will obscure critical
eyestrain and mouse acceleration issues that customers will encounter when using the product on the real hardware.
Testing on standard-density hardware will distort the test results and obscure the issues that need to be addressed.
This means that test passes for the same user interface should be conducted on different machines in order to achieve the
best results. Always choose the highest-pixel-density hardware available.
Use the following DPI and resolution guidance to complete your high-DPI testing. Prioritize your testing on Windows 8.1+,
but the experience should be consistent on Windows 7 as well.
Windows 8.1 should not automatically select 720 logical px vertical space, to allow selecting a DPI zoom factor. That
translates to 1080px at 150% zoom and 1440px at 200% zoom.
Scale
Minimum res.
Ideal res.
150%
1920 x 1080
>=2880 x 1800
200%
2560 x 1440
>=2880 x 1800
Pixels per inch
Example
MacBook Pro 15 w/ Retina (220ppi)
>=180 ppi
Dell UltraSharp 24 UP2414Q (183ppi)

MacBook Pro 15 w/ Retina (220ppi)
250%
3200 x 1800
>=3200 x 1800
>= 260 ppi
Fujitsu Lifebook (262ppi)

Samsung ATIV Book 9 plus (275ppi)
300%
3840 x 2160
>=3840 x 2160
>= 280 ppi
Toshiba Satellite (282ppi)
The ideal resolution is dependent on how the device is used, because it pertains to the viewing distance from the screen
to the eye. For information on designing for monitors of all sizes, see the MSDN post Scaling to different screens.

Testing with more than one display

Developers tend to use more than one display. With the introduction of Windows 8.1, the experience of using displays of
differing pixel densities has improved. However, this new complexity introduces challenges to building applications that
work well in this environment.
Windows 8.1 recognizes the separate ppi scaling settings for each individual monitor (controlled through a single slider in
Control Panel). This means a Visual Studio user could be using Visual Studio with a mix of low- and high-density screens
where some windows appear on one monitor with high density, and some windows on a low-density display (or
projector). An example of this is the lab setup for testing HDPI:
Display 1: High-density display running at 150%, 200%, or 250% (for example, Fujitsu Lifebook)
Display 2: Low-density external monitor running at 100% or 150% (for example, Dell 27 desktop display)
Additional information is available on the Extreme Windows Blog post Windows 8.1 DPI Scaling Enhancements.
A recommended method for multi-monitor DPI testing in Visual Studio:
1.
Start on HDPI display at 150% and proceed with a single/step validation.
2.
Drag Visual Studio to the second low-density monitor.
3.
If the validation involves a dialog, tool windows, or piece of moveable UI, drag it to the second monitor.
4.
Repeat validation at 200% and 250%.
Example issues to look for:
Windows that do not scale on the secondary display

Pop-up UI components (windows, dialogs, menus, tooltips, and so on) that look wrong or show up in the wrong
place
Custom cursors that do not change between monitors
Clickable regions (drag points, tree disclosure triangles, anchors) that become too small to click easily on the
secondary display
Rendering issues when the application or any of its windows straddles between the primary and secondary
display
Recommended HDPI devices

The following devices are recommended:
Fujitsu U904 3200 x 1800 resolution and 250% scaling
Toshiba Satellite 3840 x 2160 resolution and 300% scaling
Dell UltraSharp 24 monitor 3840 x 2160 resolution and 200% scaling. Not recommended for 250% or 300%
scaling.
Dell 28 Ultra HD monitor 3840 x 2160 resolution and 200% scaling. Not recommended for 250% or 300%
scaling.

HDPI requirements: Addressing DPI issues

For complete documentation about desktop DPI scaling and awareness, see the MSDN article Writing High-DPI Win32
Applications.
Windows has a way of dealing with scaling up UI to take advantage of increased pixel counts. An application opts in to
this system by declaring itself system DPI aware. Applications that do not do this are scaled up by the system. This can
result in a fuzzy user experience where the entire application is uniformly pixel-stretched. For example:
Visual Studio opts-in to being DPI scaling-aware, and therefore is not virtualized.
Windows (and Visual Studio) leverage several UI technologies, which have differing ways of dealing with scaling factors set
by the system.
WPF measures controls in a device-independent way (units, not pixels). WPF UI automatically scales up for the
current DPI.
All text sizes regardless of UI framework are expressed in points, and so are treated by the system as DPIindependent. Text in Win32, WinForms, and WPF already scale up correctly when drawn to the display device.
Win32/WinForms dialogs and windows have means for enabling layout that resizes with text for example,
through grid, flow, and table layout panels. These enable avoiding hard-coded pixel locations that are not scaled
when the font sizes are increased.
Icons provided by the system or resources based on system metrics (for example, SM_CXICON and
SM_CXSMICON) are already scaled up.
Older Win32 (GDI, GDI+) and WinForms-based UI

While WPF is already high DPI-aware, much of our Win32/GDI-based code was not originally written with DPI awareness in
mind. Windows has provided DPI-scaling APIs. Fixes to Win32 issues should use these consistently across the product.
Visual Studio has provided a helper class library to avoid duplicating functionality and ensuring consistency across the
product.
High-resolution images
A preferred way of dealing with images that are too small is to present an alternate version, appropriate for the resolution
and size it should be rendered at.
Visual Studio 2013 does not enable high-resolution image support. Enabling high-resolution images throughout the IDE
requires re-engineering key extension points to allow the system to accommodate alternate images represented by
unified resource identifiers in code. Considerations are being made for future versions of Visual Studio.
Scaling up images that are too small

Images that are too small can be scaled up and rendered on GDI and WPF using some common methods. Managed DPI
helper classes are available to internal and external Visual Studio integrators to address scaling icons, bitmaps,
imagestrips, and imagelists. Win32-based native C/C++helpers are available for scaling HICON, HBITMAP, HIMAGELIST,
and VsUI::GdiplusImage.
Scaling of a bitmap typically only requires a one-line change after including a reference to the helper library. For example:
(Unmanaged) VsUI::DpiHelper::LogicalToDeviceUnits(&hBitmap);
(WinForms) DpiHelper.LogicalToDeviceUnits(ref image);
Scaling an imagelist depends on whether the imagelist is complete at load time, or is appended at runtime. If complete at
load time, call LogicalToDeviceUnits() with the imagelist as you would a bitmap. When the code needs to load an
individual bitmap before composing the imagelist, make sure to scale the image size of the imagelist:
imagelist.ImageSize = DpiHelper.LogicalToDeviceUnits(imagelist.ImageSize)
In native code, the dimensions can be scaled when creating the imagelist as follows:
ImageList_Create(VsUI::DpiHelper::LogicalToDeviceUnitsX(16),VsUI::DpiHelper::LogicalToDevic
eUnitsY(16), ILC_COLOR32|ILC_MASK, nCount, 1);
Functions in the library allow specifying the resizing algorithm. When scaling images to be placed in imagelists, make sure
to specify the background color that is used for transparency, or use NearestNeighbor scaling (which will cause
distortions at 125% and 150%).
The following table shows examples of how images should be scaled at corresponding DPI scaling factors. The images in
green denote our best practice as of Visual Studio 2013 (100% 200% DPI scaling):
Layout issues
Common layout issues can be avoided primarily by keeping points in the UI scaled and relative to one another rather than
by using absolute locations (specifically, in pixel units). For example:
Layout/text positions need to adjust to account for scaled-up images.

Columns in grids need to have widths adjusted for the scaled-up text.
Hard-coded sizes or space between elements will also need to be scaled up. Sizes that are based only on text
dimensions are typically fine, because fonts are automatically scaled up.
Helper functions are available in the DpiHelper class:

LogicalToDeviceUnitsX/LogicalToDeviceUnitsY (functions allow scaling on X/Y axis)
int space = DpiHelper.LogicalToDeviceUnitsX (10);
int height = VsUI::DpiHelper::LogicalToDeviceUnitsY(5);
LogicalToDeviceUnits (Overloads allow scaling Rect, Point, Size, etc.)

Using the DPIHelper library/class to scale images and layout

The Visual Studio DPI Helper Library is available in native and managed forms and can be used outside of the Visual
Studio shell by other applications.
In source files, include VsUIDpiHelper.h and call the static functions of VsUI::DpiHelper class:
#include "VsUIDpiHelper.h"
int cxScaled = VsUI::DpiHelper::LogicalToDeviceUnitsX(cx);
VsUI::DpiHelper::LogicalToDeviceUnits(&hBitmap);
NOTE: Do not use the helper functions in module-level or class-level static variables. The library also uses statics for thread
synchronization and you might run into order-initialization problems. Either convert those statics to non-static membervariables, or wrap them into a function (so they get constructed on first access).
To access the DPI helper functions from managed code that will run inside Visual Studios environment:
The consuming project must reference the latest version of Shell MPF. For example: <Reference
Include="$(vsFrameworkLatest)" />
Ensure the project has references to System.Windows.Forms, PresentationCore, and PresentationUI

In code, use the PlatformUI namespace and call static functions of DpiHelper class. For supported types (points,
sizes, rectangles, etc) there are provided extension functions that return new scaled objects. For example:
using Microsoft.VisualStudio.PlatformUI;
double x = DpiHelper.LogicalToDeviceUnitsX(posX);
Point ptScaled = ptOriginal.LogicalToDeviceUnits();
DpiHelper.LogicalToDeviceUnits(ref bitmap)
Dealing with WPF image fuzziness in zoomable UI

In WPF, bitmaps are resized automatically by WPF for the current DPI zoom level using a high-quality bicubic algorithm
(default), which works well for pictures or large screenshots, but is inappropriate for menu item icons because it introduces
perceived fuzziness.
Recommendations:
For logo image and banners artwork, the default BitmapScalingMode.HighQuality resizing mode could be used.
For menu items and iconography images, the BitmapScalingMode.NearestNeighbor should be used when it
doesnt cause other distortion artifacts to eliminate fuzziness (at 200% and 300%).
For large zoom levels not multiples of 100% (for example, 250% or 350%), scaling iconography images with
bicubic results in fuzzy, washed-out UI. A better result is obtained by first scaling the image with
NearestNeighbour to the largest multiple of 100% (for example, 200% or 300%) and scaling with bicubic from
there. See Special case: pre-scaling WPF images for large DPI levels for more information.
The DpiHelper class in the Microsoft.VisualStudio.PlatformUI namespace provides a member BitmapScalingMode that
can be used for binding. It will allow the Visual Studio shell to control the bitmap scaling mode across the product
uniformly, depending on the DPI scaling factor. Additionally, the user can override this setting via the registry.
To use it in XAML, add:
xmlns:vsui="clrnamespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.12.0"
<Setter Property="RenderOptions.BitmapScalingMode" Value="{x:Static
vs:DpiHelper.BitmapScalingMode}" />
The Visual Studio shell already sets this property on top-level windows and dialogs. WPF-based UI running in Visual Studio
will already inherit it. If the setting does not propagate your particular pieces of UI, it can be set on the root element of the
XAML/WPF UI. Places where this happens include pop-ups, on elements with Win32 parents, and designer windows that
run out of process, such as Bliss.
Some UI can scale independently of the system-set DPI zoom level, such as the Visual Studio text editor and WPF-based
designers (WPF Desktop and Windows Store). In these cases, DpiHelper.BitmapScalingMode should not be used. To fix
this issue in the editor, the IDE team created a custom property in the editor called RenderOptions.BitmapScalingMode,
and set that property value to HighQuality or NearestNeighbour depending on the combined zoom level of the system
and the UI.
Special case: pre-scaling WPF images for large DPI levels

For very large zoom levels that are not multiple of 100% (for example, 250%, 350%, and so on), scaling iconography
images with bicubic results in fuzzy, washed-out UI. The impression of these images alongside crisp text is almost like that
of an optical illusion. The images appear to be closer to the eye and out of focus in relation to the text. The scaling result
at this magnified size can be improved by first scaling the image with NearestNeighbour to the largest multiple of 100%
(for example, 200% or 300%) and scaling with bicubic to the remainder (an additional 25%).
The following is an example of the differences in results, where the first image is scaled with the improved double-scaling
algorithm 100%->200%->250%, and the second one just with bicubic 100%->250%.
In order to enable UI to use this double-scaling, XAML markup for displaying each Image element will need to be
modified. The following examples demonstrate of how to use double-scaling in WPF in Visual Studio using the DpiHelper
library and Shell.12/14.
Step 1: Pre-scale the image to 200%, 300%, and so on using NearestNeighbour.
Pre-scale the image using either a converter applied on a binding, or with a XAML markup extension. For example:
<vsui:DpiPrescaleImageSourceConverter x:Key="DpiPrescaleImageSourceConverter" />
<Image Source="{Binding Path=SelectedImage, Converter={StaticResource

DpiPrescaleImageSourceConverter}}" Width="16" Height="16" />
<Image Source="{vsui:DpiPrescaledImage Images/Help.png}" Width="16" Height="16" />

If the image also needs to be themed (most, if not all, should), the markup can use a different converter that first does
theming of the image and then pre-scaling. The markup can use either DpiPrescaleThemedImageConverter or
DpiPrescaleThemedImageSourceConverter, depending on the desired conversion output.
<vsui:DpiPrescaleThemedImageSourceConverter
x:Key="DpiPrescaleThemedImageSourceConverter" />
<Image Width="16" Height="16">

<Image.Source>
<MultiBinding Converter="{StaticResource DpiPrescaleThemedImageSourceConverter}">
<Binding Path="Icon" />

<Binding Path="(vsui:ImageThemingUtilities.ImageBackgroundColor)"
RelativeSource="{RelativeSource Self}" />
<Binding Source="{x:Static vsui:Boxes.BooleanTrue}" />
</MultiBinding>
</Image.Source>
</Image>
Step 2: Ensure the final size is correct for the current DPI.
Because WPF will scale the UI for the current DPI using the BitmapScalingMode property set on the UIElement, an Image
control using a pre-scaled image as its source will look two or three times larger than it should. The following are a couple
ways to counter this effect:
If you know the dimension of the original image at 100%, you can specify the exact size of the Image control. These sizes
will reflect the size of the UI before scaling is applied.
DpiPrescaleImageSourceConverter}}" Width="16" Height="16" />
If the size of the original image is not known, a LayoutTransform can be used to scale down the final Image object. For
example:
DpiPrescaleImageSourceConverter}}">
<Image.LayoutTransform>
<ScaleTransform
ScaleX="{x:Static vsui:DpiHelper.PreScaledImageLayoutTransformScale}"
ScaleY="{x:Static vsui:DpiHelper.PreScaledImageLayoutTransformScale}" />
</Image.LayoutTransform>
</Image>

Enabling HDPI support to the WebOC

By default, WebOC controls (such as the WebBrowser control in WPF, or the IWebBrowser2 interface) dont enable HDPI
detection and support. The result will be an embedded control with display content that is too small on a high-resolution
display. The following describes how to enable high-DPI support in a specific web WebOC instance.
Implement the IDocHostUIHandler interface (see the MSDN article on the IDocHostUIHandler interface):
[ComImport,
InterfaceType(ComInterfaceType.InterfaceIsIUnknown),
Guid("BD3F23C0-D43E-11CF-893B-00AA00BDCE1A")]
public interface IDocHostUIHandler
{
[return: MarshalAs(UnmanagedType.I4)]
[PreserveSig]
int ShowContextMenu(
[In, MarshalAs(UnmanagedType.U4)] int dwID,
[In] POINT pt,
[In, MarshalAs(UnmanagedType.Interface)] object pcmdtReserved,
[In, MarshalAs(UnmanagedType.IDispatch)] object pdispReserved);
[PreserveSig]
int GetHostInfo(
[In, Out] DOCHOSTUIINFO info);
[PreserveSig]
int ShowUI(
[In, MarshalAs(UnmanagedType.I4)] int dwID,
[In, MarshalAs(UnmanagedType.Interface)] object activeObject,
[In, MarshalAs(UnmanagedType.Interface)] object commandTarget,
[In, MarshalAs(UnmanagedType.Interface)] object frame,
[In, MarshalAs(UnmanagedType.Interface)] object doc);
[PreserveSig]
int HideUI();
[PreserveSig]
int UpdateUI();
[PreserveSig]
int EnableModeless(
[In, MarshalAs(UnmanagedType.Bool)] bool fEnable);
[PreserveSig]
int OnDocWindowActivate(
[In, MarshalAs(UnmanagedType.Bool)] bool fActivate);
[PreserveSig]
int OnFrameWindowActivate(
[In, MarshalAs(UnmanagedType.Bool)] bool fActivate);
[PreserveSig]
int ResizeBorder(
[In] COMRECT rect,
[In, MarshalAs(UnmanagedType.Interface)] object doc,
bool fFrameWindow);
[PreserveSig]
int TranslateAccelerator(
[In] ref MSG msg,
[In] ref Guid group,
[In, MarshalAs(UnmanagedType.I4)] int nCmdID);
[PreserveSig]
int GetOptionKeyPath(
[Out, MarshalAs(UnmanagedType.LPArray)] string[] pbstrKey,
[In, MarshalAs(UnmanagedType.U4)] int dw);
[PreserveSig]
int GetDropTarget(
[In, MarshalAs(UnmanagedType.Interface)] IOleDropTarget pDropTarget,
[MarshalAs(UnmanagedType.Interface)] out IOleDropTarget ppDropTarget);
[PreserveSig]
int GetExternal(
[MarshalAs(UnmanagedType.IDispatch)] out object ppDispatch);
[PreserveSig]
int TranslateUrl(
[In, MarshalAs(UnmanagedType.U4)] int dwTranslate,
[In, MarshalAs(UnmanagedType.LPWStr)] string strURLIn,
[MarshalAs(UnmanagedType.LPWStr)] out string pstrURLOut);
[PreserveSig]
int FilterDataObject(
IDataObject pDO,
out IDataObject ppDORet);
}
Optionally, implement the ICustomDoc interface (see the MSDN article on the ICustomDoc interface):
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown),
Guid("3050F3F0-98B5-11CF-BB82-00AA00BDCE0B")]
public interface ICustomDoc
{
void SetUIHandler(IDocHostUIHandler pUIHandler);
}
Associate the class that implements IDocHostUIHandler with the WebOCs document. If you implemented the
ICustomDoc interface above, then as soon as the WebOCs document property is valid, cast it to an ICustomDoc and call
the SetUIHandler method, passing the class that implements IDocHostUIHandler.
// this references that class that owns the WebOC control and in this case also implements
the IDocHostUIHandler interface
ICustomDoc customDoc = (ICustomDoc)webBrowser.Document;
customDoc.SetUIHandler(this);

If you did NOT implement the ICustomDoc interface, then as soon as the WebOCs document property is valid, youll need
to cast it to an IOleObject, and call the SetClientSite method, passing in the class that implements IDocHostUIHandler.
Set the DOCHOSTUIFLAG_DPI_AWARE flag on the DOCHOSTUIINFO passed to the GetHostInfo method call:
public int GetHostInfo(DOCHOSTUIINFO info)
{
// This is what the default site provides.
info.dwFlags = (DOCHOSTUIFLAG)0x5a74012;
// Add the DPI flag to the defaults
info.dwFlags |=.DOCHOSTUIFLAG.DOCHOSTUIFLAG_DPI_AWARE;
return S_OK;
}
This should be all that you need to get your WebOC control to support HPDI.
Tips
1.
If the document property on the WebOC control changes, you might need to reassociate the document with the
IDocHostUIHandler class.
2.
If the above does not work, there is a known issue with the WebOC not picking up the change to the DPI flag. The
most reliable way of fixing this is to toggle the optical zoom of the WebOC, meaning two calls with two different
values for the zoom percentage. Additionally, if this workaround is required, it might be necessary to perform it on
every navigate call.
// browser2 is a SHDocVw.IWebBrowser2 in this case

// EX: Call the Exec twice with DPI%-1 and then DPI% as the zoomPercent values
IOleCommandTarget cmdTarget = browser2.Document as IOleCommandTarget;
if (cmdTarget != null)
{
object commandInput = zoomPercent;
cmdTarget.Exec(IntPtr.Zero,
OLECMDID_OPTICAL_ZOOM,
OLECMDEXECOPT_DONTPROMPTUSER,
ref commandInput,
ref commandOutput);
}

11: Accessibility

2015 RC PREVIEW
Accessibility
At Microsoft, our commitment to developing innovative accessibility solutions began more than two decades ago and
continues with each new product we develop. Accessibility, as part of overall usability, is a fundamental consideration for
Microsoft during product design, development, evaluation, and release.
-
From History of Microsoft Commitment to Accessibility
User-Friendly Tenet requirements

Accessibility is part of the User-Friendly Tenet to drive feature criteria. At a minimum, accessibility within Visual Studio
means a scenario/feature/experience addresses the items on this checklist:
1.
Keyboard navigation and focus: all user scenarios can be accomplished without the mouse. A logical tab
order has been set, with consistent navigation throughout the product. Focus is always apparent.
2.
Screen reader: all user scenarios for the feature can be accomplished with via Narrator.
3.
High Contrast: all user scenarios can be complete in High Contrast mode.
4.
Programmatic access: applicable controls can be used via control patterns (for example, Toggle.Toggle,
Invoke.Invoke, Value.SetValue, and ExpandCollapse.Expand/Collapse). The state of the control is correctly
reported regardless of how the change was invoked, including any combination of keyboard, mouse, and
control pattern (for example, disabled=true/false, pressed=true/false).
5.
Other accessibility considerations:
Never convey information alone by color, shape, size, location, or orientation.
Always use alt text for images.
Never use flashing UI.
Always provide context when linking that describes the purpose of the link, preferably in the linked text
itself.
Always describe user input errors in text and give actionable suggestions to correct them.
Always provide a way within services and web applications to reverse, verify, or confirm user input that
results in a legal commitment, financial transaction, or database modification.
Always allow a user to pause or control time limits for response and the frequency of any UI that autorefreshes or auto-updates.
Microsoft Accessibility Standard (MAS)

The Microsoft Accessibility Standard (MAS) applies to all Microsoft products. For general guidance on MAS, visit Microsoft
Accessibility on the Web. The following are specific principles you should consider when designing UI for Visual Studio.
Color usage in features

Color should never be used to convey meaning in a UI, as visually impaired users are not able to see on-screen color
changes. Although color should be used to accent content in your UI, it must never be used as the primary conveyor of
information to the user. For more information, read the MSDN article Can Color-Blind Users See Your Site?
Assistive technologies and active accessibility objects

Every control in a feature's UI must have an Active Accessibility (AA) object associated with it. The AA component,
oleacc.dll, creates proxy objects that implement IAccessible on behalf of standard Windows controls.
Assistive technologies, such as Freedom Scientific's JAWS or GW Micro's Window Eyes, use AA objects to speak a control's
type, description, and current value.
304 Visual Studio UX Guidelines: Accessibility
Microsoft Active Accessibility (MSAA)

This table shows the MSAA properties that should be localized:
Property
Comment
Name
With the exception of standard Windows scrollbars.
Value
For example, the content within an edit box or a combo box should be localized to match what is on
the screen.
Description
A concise summary.
Help
Use this to describe the content in tooltips.
DefaultAction
If you are using one of the given DefaultActions listed in oleaccrc.dll, this will be localized
automatically.
KeyboardShortcut
Should be localized as needed to support the localized product; which shortcuts and which
mnemonics get localized is language-dependent.
RoleText
Provided you are using one of the given roles listed in oleaccrc.dll, you should get this for free.
StateText
Automatically localized if one of the given states is used.
Drop-in component for your spec

For most situations, you should be able to drop the following checklist into your feature specification and cover the basic
requirements:
Every control present in this spec has an MSAA object associated with it.
The features present in this spec do not depend on colors to convey information to the user.
The features present in this spec are keyboard-accessible. Each essential control has an assigned keyboard access
key and has a tab-order position that corresponds to its visual layout.
All user scenarios must be accomplishable via keyboard.
Visual Studio UX Guidelines: Accessibility 305

Contrast ratios
There are specific contrast ratios that need to be met in order to pass our accessibility requirements. These contrast ratios
are required for the default theme (blue) and the Windows settings for high-contrast, which Visual Studio displays when it
detects that the operating system is in high-contrast mode. In Light and Dark themes, which depend on subtle variations
to define the personalities of those theme, these requirements are relaxed.
Text contrast
MAS 17 standard for Visible Text Contrast. By default, text must have a minimum luminosity contrast ratio of 4.5:1
against the background. Exceptions include logos and incidental text.
Icon contrast
By default, icons must have luminosity contrast ratio of 5:1 against the background.
High Contrast
High Contrast provides a minimum luminosity contrast ratio of 14:1. Visual Studio must respect the system (platform)
setting for High Contrast.
Keyboard accessibility
Our users must never be blocked from using any functionality because the feature is not keyboard-accessible. Users who
are blind cannot use the mouse, and many sighted users prefer pure keyboard usage. To ensure that a feature is
keyboard-accessible:
Assign an access key to each essential control, tool window, menu item, and so on.
Give every control a tab-order position that corresponds to its visual layout (left-to-right and top-to-bottom for
left-to-right languages).
306 Visual Studio UX Guidelines: Accessibility

12: Animations

2015 RC PREVIEW
Animations: Animation fundamentals

Follow these rules to ensure consistent and user-friendly animation styles across Visual Studio's IDE.
Be selective. Limit animations to those that serve specific purposes.
Timing and speed are important to ensure that transitions feel quick and natural:
o
Complete animated transitions within one half-second (500 milliseconds).
Animations that would occur frequently need to be quick enough that they don't interrupt the user's
workflow.
Animations should not be so fast or jarring that it is difficult to understand, but not so slow that it makes
one impatient for the transition to finish.
Use variable timing to emphasize importance. For example, when navigating through a sequence of items
on a class diagram, speed through transitions between items then slow down to focus on important items.
Use gradual non-linear easing from one state to another, giving a sense of calm and natural movement.
When possible, use a subtle animation on hover to indicate interactive elements under the mouse.
If you rely heavily on animations in your features then provide a means to turn them off locally (for all your
features) as an option in the Tools/Options dialog.
Only one animation should occur at a time and convey just one piece of information.
Subtlety is important. In most cases animation doesn't have to demand user attention to serve its purpose. Subtle
changes in timing, sequencing, and behavior may significantly impact perception, and can make the difference
between an effective and ineffective animation.
When using animation to draw attention to something, make sure that it is worth interrupting the user's train of
thought.
When showing progress or status through animation:

o
Stop showing progress movement when the underlying process is not advancing.
Distinguish indeterminate processes from determinate processes.
Ensure that an animation has identifiable completion and failure states.
Minimize use of effect animations that show status and make sure that they have real value by providing
additional information of actual use. Examples include transient status changes and emergencies.
Do not:
Use small movements (movement in a small footprint), preferring fades and changes over moving objects.
Use animations that take place over a large area of screen real estate. Regardless of size, this style of animation is
distracting to the user.
Use animations that do not relate to the object the user is currently focused on or interacting with.
Use animations that require user interaction to reset the state, such as forcing the user to respond to a flashing
notification in order to make it stop flashing. Interacting with them in any way should be sufficient to dismiss
them.
For more information on applications for these best practices see Animation patterns.
Animation metrics
The system should visibly react to user gestures in less than 10 milliseconds.
Animated transitions should not take longer than 500 milliseconds to complete.
One way to compensate for transitions that require longer times is to separate it into two parts; for example, the
first part of an animation could be the empty content container (up to 500 milliseconds) followed by the content
fading into the container (up to 500 milliseconds).
308 Visual Studio UX Guidelines: Animations

EARLY PARTNER PREVIEW OF 2015 GUIDELINES. SUBJECT TO CHANGE. FOR QUESTIONS OR FEE DBACK, EMAIL UXBOARD@MICROSOFT.COM.
For load times that can be calculated, a determinant progress indicator (percent-done progress indicator) is
preferred.
For load times that cannot be calculated, a busy indicator such as a cursor or embedded spinning animation
(loading or working indicator) is appropriate.
Animation as communicator
In Visual Studios UI, animation functions only as a communication tool. It is used to communicate a variety of
information, such as structural changes in the UI; for example, when a menu opens or closes. Animation can help visualize
the time-dependent behavior of complex systems, such as installation progress visualization or be used to attract
attention with alerts and notifications.
UI animations typically function in four ways: visualize, attract attention, simulate, and indicate response times/progress.
Visualize
Animation can emphasize the three-dimensional nature of objects and make it easier for users to visualize their spatial
structure. To achieve this, the animation may need to spin the object in a full circle, slowly turn it back and forth, or bring
the object closer and slightly increase its size to emphasize rollover or focus.
Although three-dimensional objects may be moved with user control, the designer should determine in advance
(programmatically or manually) how to best animate a movement that provides optimal understanding of the object. This
programmed animation can then be activated by the user by placing the cursor over the object, whereas user-controlled
movements require the user to understand how to manipulate the object. Limit the movement to a single axis or
orientation at a time; either scale, rotate, or translate, but don't do more than one simultaneously.
The Visualize category includes the aspects of data, relationships, state, structure, sequence, and time.
Data
Illustrate complex and variable information:
Moving through information visualizations like charts and graphs.
Stepping through a sequence, guided tour, and paging.
Calling out details, pointing, and highlighting specific information.
Overlaying details and additional information on top of a focused element.
Morphing from one structural or organizational representation to another.
Representing changes over time using time sliders, jog-and-shuttle wheels, and transport controls (play, stop, and
pause).
Relationships
Illustrate how items relate to one another or which items relate to a given item.
Show hierarchies and parent-child or sibling relationships.
One element spawns another.
One element minimizes to another element.
One element tethered to another.
State
Content updates.
User focus and selection.
Progress.
Errors.
Visual Studio UX Guidelines: Animations 309
Structure
Pivoting the structure on one node.
Reorienting.
Minimize and maximize or expand and collapse.
Sequence
Slideshow sequence.
Flipping through pictures.
Time
Show change over time, time lapse, and screencast.
Move to trash, undo, and redo.
Restore historical state.
Attract attention
If the goal is to draw the user's attention to a single element out of several or to alert the user to updated information,
then an animation may be appropriate. For example, your applications start page might employ a Getting Started button
that slides into place after the page loads.
As a rule, the last moving element on the screen attracts the users attention. In a series of animated elements, the users
attention will follow the last moving object.
Alert
Alert the user, get attention, show progress.
Show that something is being done correctly or incorrectly or show progress or progress changes.
Prompt users during a task, such as finding out more information online or learning about the current task.
Notifications
Alert the user about an error condition.
Interrupt the user to see if they would like to attend to something else.
Gently inform the user that a process has completed or changed, such as when a download is complete.
Simulate
This category covers physicality and dimensionality.
Illustrate from where objects come or to where they go.
Expand and collapse or open and close.
Panning, scrolling, and page turns.
Stacking and z-ordering.
Carousel and accordion.
Flipping and rotating UI.
Response/progress indicators
Progress indicators have a couple of notable advantages:
Both determinate and indeterminate progress indicators reassure the user that the system has not crashed and is
working on the problem.
Determinant indicators give the user a sense of how far along the action is progressing, as well as a feeling of
getting closer to the finish.

Animations: Animation patterns

Animations in Visual Studio are meant to serve a specific function and not hinder user productivity. General animation
characteristics to which to adhere include:
Small and unobtrusive
Natural and realistic
Subtle and subdued
Fast and efficient
Relaxed, not hurried
The following illustration shows the animation styles recommended for use in Visual Studio. No animation and subtle
animations such as fade in/fade out are the most frequently used. There is limited application of movement animations
such as expand and contract, X and Y position change, and rotation.
Recommended animation styles for Visual Studio
Appear and disappear

With this pattern, an element switches from visible to out-of-view and back without a transition animation:
Correct usage
Fresh UI elements that need to instantly appear or disappear so that the user is neither distracted nor obstructed. In
addition, slow moving animations may be perceived as a performance drag, which won't occur with the appear-anddisappear style.
Incorrect usage
Cases in which UI appears so abruptly the user has no idea what happened, and adding an animation would help with
contextual understanding.

Animation properties
The time delay is generally zero seconds.
Examples
Auto-hide tool windows
Keyboard activated editor UI such as IntelliSense and parameter Help
Expand-and-collapse code regions
Fade-in and fade-out

With this pattern, a UI element transitions from not visible (0% opacity) to visible (100% opacity) or vice-versa:
Correct usage
This is the most commonly recommended UI animation. It is a subtle effect that adds interest without interrupting flow. In
some cases, the user may not even realize that there is an animation and simply perceives a smooth, flowing UI system.
Starting opacity: 0% for fade in, 100% for fade out
Ending opacity: 100% for fade in, 0% for fade out
Duration: 200 milliseconds standalone; 100 milliseconds when used as part of a combination animation sequence
Easing style: Sine InOut
Examples
Auto-hide tool windows
Menu open and close
Background and foreground tab transitions
Color blend from A to B

With this pattern, a UI element changes from color A to B:
Correct usage
As an animated transition when a UI element changes color from one context or state to another.
Starting color: UI-specific
Ending color: UI-specific
Examples
Document window state transitions (active, last active, and inactive)
Tool window state transitions (focused and unfocused)

Expand and contract

With this pattern, a UI element expands in the X, Y, or both directions:
Correct usage
As an animated transition when a UI element changes size from one context to another.
X scale: % or specific dimension (in pixels)
Y scale: % or specific dimension (in pixels)
Anchor position: Generally upper-left (for left-to-right languages) or upper-right (for right-to-left languages)
Examples
Architecture Explorer panel expand and collapse
Start Page item expand and collapse
X-Y position change

With this pattern, a UI element changes its X or Y position or both:
Correct usage
As an animated transition when a UI element changes position from one context to another.
Starting X and Y position: UI-specific
Ending X and Y position: UI-specific
Motion path: None
Example
Tab reordering

Rotate
With this pattern, the UI element rotates:
Correct usage
Only for the indeterminate spinning progress indicator.
Degree of rotation: 360
Rotation center: Middle of the object
Duration: Continuous
Example
Indeterminate progress indicator (spinning)

Common shell UI actions and recommended animations

Tab open
Style: Appear
Duration: Zero seconds
Tab close
Style: X position change
Duration: 200 milliseconds
Tab reorder
Style: X position change

Close floating document
Style: Appear
Window state transition
Style: To be consistent with other windows, let the current operating system define the document close animation.
For Windows 7, the windows fade out and contract.

Menu open
Style: Fade-in
Menu close
Style: Fade-out

Auto-hide tool window reveal
Style: Appear
Duration: Zero seconds

13: World Readiness

2015 RC PREVIEW
World Readiness
Designing UI that will be localized
There are two key considerations when designing UI that will be localized:
1.
2.
Adjust UI elements if the English text is being translated into localized languages. Minimize the time-consuming
and costly step of having the localization team review and reposition clipped or overlapping elements.
Design the English language Visual Studio UI to adapt gracefully to the larger, fixed-width fonts of East Asian
operating systems. Although Western and East Asian language versions of Windows share the same system font
size (9pt), East Asian fonts are monospace and therefore wider than the proportional Segoe UI font found in
Western languages. No automatic adjustment can be made to accommodate the UI changes resulting from the
different Roman base font used on Asian operating systems, so the English UI must be engineered in such a way
as to adapt gracefully to the larger font.
It is far easier to deal with localization issues early on than to run into bugs late in the development cycle. User experience
designers and program managers need to know their localization contacts and keep them in the loop when designing new
UI. The following list details important localization considerations:
Create generic icons and images that do not have to be localized, and never place text into bitmaps where it
cannot be accessed by localization tools.
Allow for at least a 30% increase in text expansion, unless auto layout controls are used (available only in
managed dialogs).
Allow for at least one extra line in text boxes when a variable is used within a sentence.
Do not use UI controls within a sentence.
Make sure all localizable strings are not hard-coded.
Set the text for multi-line and top alignment so that text can be wrapped, which is crucial for text that appears
after check boxes and radio buttons.
If possible, do not put the text for dialog controls in the string table but rather in the dialog resource itself. This
applies to buttons, dialog items, and menu items. This makes it possible to localize in context and easily identify
clipping issues.
Do not combine strings at runtime to form new strings.
Do not separate a sentence string into several strings.
Do not use more than one placeholder per message if they are of different types, for example string and int.
Enumerate placeholders if more than one is used.
Do not assume that the sentence structure is for the English language when the sentence contains placeholders.
Use consistent terminology: choose the most common, understandable term and use it throughout.
Make consistent and correct use of grammar, such as period (.), colons (, ; :), and capitalization.
Do not use colloquialisms.
Work with your localization contact on any web UI that has special localization issues.
WPF UI localization
WPF (Windows Presentation Foundation) UI localization requires development engineering team action and is a
prerequisite to the localization process. You need to ensure that your WPF UI can display the new resources that your
localization organization provides to you. The techniques for WPF are no different than any other presentation technology,
such as not using fixed width controls for localizable strings.
Here are some top points from the WPF Globalization and Localization Overview page in the MSDN Library:
Avoid using absolute positions and fixed sizes to lay out content; instead, use relative or automatic sizing.
Use SizeToContent; and keep widths and heights set to Auto.
Avoid using Canvas to lay out UIs.
320 Visual Studio UX Guidelines: World Readiness

Use Grid and its size-sharing feature.

Provide extra space in margins, because localized text often requires more space. Extra space allows for possible
overhanging characters.
Enable TextWrapping on TextBlock to avoid clipping.
The FlowDirection property value only needs to be explicitly set for elements that must maintain a static direction.
For all other elements, the direction is dictated by localization.
If property inheritance doesn't apply (for example, in the case of an intervening HWND), then explicitly set
FlowDirection to RightToLeft.
Favor the use of DockPanels and StackPanels.
When using paths, ensure that the control behaves correctly in right-to-left (RTL) languages; If you do not require
the path to be mirrored, then enforce a FlowDirection of LeftToRight in the resource styles.
When using screen coordinate operations, ensure that RTL is working properly (for example, for drag-and-drop
operations).
In order to ensure legibility across major languages, never specify a FontSize attribute value of less than 12.
Language pack design

In addition to a full product installation, Visual Studio 2012 supports independent language pack install scenarios. Teams
adding on VS should be aware of and consider the following:
How they design their install/uninstall scenario to light up if multiple language packs are installed on a system.
That additional language packs could be installed/uninstalled or new ones added at any time to a given
installation.
Application localization model design

Technologies should have a means of localizing their application types. When it comes to supporting, debugging
scenarios, build and package considerations, consider the following:
That the application can be debugged in a new target language without having to re-start VS or OS user session.
That the ultimate fallback language is configurable.
That servicing requirements or incremental language roll-outs may require independent packaging and versioning
of core and language packs.
Globalization baseline
Having a globalization baseline sets general globalization functionality objectives across the product which are to be met
by multiple product teams. It supports a uniform international experience that is aligned with partner expectations, MS
business goals, and standard international best practices. It also helps teams avoid international and compliance snares.
All product/feature scenarios must pass using English Visual Studio/.NET Framework on the globalization platform matrix
under the following conditions (except where limited by the host platform and/or external dependencies):
All features are fully functional across language versions and locales (that is, major usage scenarios are available
globally).
All features support Unicode, including Unicode surrogate pairs (for example, default to Unicode encoding, data
types, APIs).
All features support international keyboard input, including the use of Windows and Office-provided Input
Method Editors (full in-line composition for Korean, minimum of cursor-positioned composition for Japanese,
Simplified and Traditional Chinese).
All multi-tier components can operate under non-matching Windows locales and UI language versions.
All features fully meet the GB18030 requirements, enabling the product to pass PRC certification.
All features support the Chinese minority scripts on Vista and later Windows releases.
All features support complex scripts, including bidirectional languages.
Visual Studio UX Guidelines: World Readiness 321
14: Evaluation Tools

2015 RC PREVIEW
Evaluation tools: Craftsmanship checklist

Use this checklist to evaluate user experience quality for visual and interaction details.
Overview
Verify that all commands result in feedback that tells users that their commands have been carried out.
Verify that all UI elements and controls are visible in all themes and in High Contrast mode.
Verify that inactive and active selection are always differentiated, both in standard and High Contrast mode.
Verify that focus is always visible and apparent.
Performance
Verify that some kind of busy indicator is shown if a command takes more than one second to complete.
Verify that if a command takes more than 10 seconds to complete, an explicit progress bar, either determinate
(preferred) or indeterminate, is displayed.
UI text
Verify that all labels are sentence- or title-case and that no text is entirely lowercase.
Correct
Incorrect
Command text (all)
Sentence case:
Directory name:
Directory Name:
Button text (client)
Title case:
[ Set As Default ]
SET AS DEFAULT
Button text (online)
Sentence case:
[ Set as default ]
Verify that all labels, except group headers and buttons, end with a colon and precede the control with which they are
paired.
Verify that buttons, commands, and command links that launch UI to capture user input end in an ellipsis [...].
Examples:
An [ Advanced...] button on a dialog.
The command options under the Tools menu (Tools > Options) should not get an ellipsis, because
launching the dialog itself is the intent of the command.
Verify that the UI contains no abbreviations, except for industry-standard terms. For instance, neither HTML nor
TCP/IP need to be spelled out, though OOM (out of memory) and PII (personally identifiable information) should.
Keyboard access
Verify that there is a way to accomplish each task with the keyboard. Generally this is accomplished through
keyboard access for each control, but for some highly visual areas, a workaround such as going to code view is
acceptable.
324 Visual Studio UX Guidelines: Evaluation Tools

Verify that you can Tab through controls in a logical order (left-to-right and top-to-bottom). While this is a best
practice for most controls, not all controls require this approach. For example, verify that radio button controls are
in a group with a single tab stop.
Verify that all controls have labels and that each label has a mnemonic (exceptions include some non-labeled
controls that might follow a labeled control in the tab).
Verify that there are no mnemonic conflicts.
Fonts
Verify that all fonts (face, size, color) are used consistently and maintain hierarchy.
Verify that all UI elements use the Environment Font Service.

To check if the service is being used, go to Tools > Options > Fonts and Colors. In the Settings dropdown,
choose Environment Font and change the font face to something stylistically different (such as Harrington or
Comic Sans) and set the size to 12 pt. Then click OK. You might need to restart the IDE, but most UI will change
immediately. Areas that don't pick up the font change even on restart are not using the Environment Font.
Verify that fonts that are derivative of the service (for example, bold or enlarged text) retain their size and
formatting in relation to "normal" text when the Environment Font size is changed.
Verify that there are no clipping bugs due to enlarged fonts. Fonts that get clipped are likely the result of fixed
height controls or fixed height containers.
Dialogs
Verify that the dialog title is the same as the command that launched it.
Verify that all standard controls are consistent with the operating system: background color is standard and no
controls should have a special re-templated style that makes them appear different from standard controls.
Verify that margins within the form should be 12 pixels and should appear uniform and consistent.
Verify that dialogs appear centered within the integrated development environment (IDE) shell or the window that
spawned them.
When useful, dialogs should be resizable. For dialogs that are resizable, verify that upon resizing, the appropriate
controls must resize while other parts of the dialog remain constant.
Verify that resizable dialogs persist any user-adjusted size (size, location, expansion of dialog controls, etc.).
Verify that there is no icon in the title bar.
Verify that there are no Minimize and Maximize buttons in the title bar.
Dialog operation buttons
Verify that operation buttons are in this order: OK, Cancel, Apply.
Verify that OK and Cancel buttons are the standard size: 75x23 pixels.
If the label on an operation button requires the button to be wider than standard, verify that the corresponding
Cancel button is of equal size.
Verify that there is a 6-pixel padding between buttons and associated controls.
Verify that the OK and Cancel buttons do not have mnemonics (access keys defined by an underlined letter).
Verify that one button (typically OK) has focus by default.
Verify that Esc cancels the dialog.
Verify that Enter executes the default button if focus is not in a control that processes Enter.
Verify that the OK and Cancel buttons are positioned in the bottom right corner of the dialog. In rare exceptions, it
is acceptable for them to be stacked vertically in the upper right.
Verify that the vertical configuration is used only if other buttons are in a horizontal alignment within the dialog.
Visual Studio UX Guidelines: Evaluation Tools 325
Control standards
General
Verify that, when possible, there are good default values to speed up user interaction and direct users toward a
safe or common outcome.
Verify that standard controls behave the same way so that users know what will happen based on earlier
experience.
Label controls
Verify that each control has a label and that each label is visually paired with its control (generally within a 4-6
pixel range) and is closer to its corresponding control than to other controls.
Verify that labels are positioned flush left with the control left edge if positioned above and centered horizontally,
so that the baseline of the label is aligned with the baseline of the input text if positioned to the left.
Verify that if several stacked label and input controls are positioned to the left of a control, the labels are flush left
and an equal distance from the edge of the dialog, never flush right and an equal distance from the controls. Pairs
should be evenly distributed unless they need additional spacing to indicate grouping.
Input controls (text boxes and combo boxes)
Verify that when using the default environment font, the display height for text boxes, combo boxes and buttons
are all 23 pixels.
If hint text is used, verify that the color is set to Environment.ControlEditHintText using the color service.
If the field is a required field that must be identified as such, verify
that the background is set to Environment.ControlEditRequiredBackground and the foreground is set to
Environment.ControlEditRequiredHintText
that there is hint text within the control that appears as <Required>
Button controls
Verify that buttons are a minimum size of 75x23 pixels, unless accommodating longer text.
Verify that buttons have left and right margins of 3-5 pixels, as well as padding for the content.
It is acceptable to use a small square button with only an ellipsis [...] on it instead of a Browse... button (or similar
functionality). If used, verify that the button is 23x23 in size.
If there is more than one Browse... button in a dialog, then verify that the shortened version (ellipsis only) is used
for all.
Verify that ellipsis [...] buttons do not have a mnemonic. When focus is on the input control beside it, one tab
should move focus to the ellipsis button.
Verify that buttons, commands, and command links that launch secondary UI that captures more user input must
end in an ellipsis [...].
Hyperlinks
Verify that a hyperlink control never flashes red when active. This is an indicator that the color service is not being
used.
Verify that the VS Colors used are:
Environment.ControlLinkText
Environment.ControlLinkTextHover
Environment.ControlLinkTextPressed
Verify that hyperlinks appear blue with no underline unless embedded in a paragraph
326 Visual Studio UX Guidelines: Evaluation Tools

Checkboxes
If a checkbox has multi-line text, verify that the box aligns with the first line of text, not centered vertically across
all lines.
Verify that checkboxes always indicate a binary choice and do not navigate the user or open new windows or
pages.
If a checkbox presents an option related to an input control, verify that it is positioned flush left and very close
under that control to indicate its relation.
Verify that a checkbox is NEVER used as a means to enable the entire contents of a dialog or page.
Group boxes
Verify that a dialog does not contain a single group box within it that contains the entire contents of the dialog.
Verify that there are at least two controls within each group box.
Rarely should there be more than two group boxes on a dialog.
Verify that there are no nested group boxes.
Icons
Verify that icons appear correctly inverted when in the dark theme.
Verify that all icons are based on core concepts.
Verify that each icon is distinct, easy to recognize and does not contain more than two concepts (without status
modifier/language).
Verify the base icon appear centered within the space.
Verify that all icons appear legible in high-contrast mode.
Verify that any color used aligns with color usage standards.
Verify that there are no halos (borders) around icons. (If present, the halo should match the background color of
the adjacent UI).
Touch-enabled UI
Verify that interactive controls are large enough to be easily touchable minimum 23x23 pixels in size.
Verify that the most frequently used controls are at least 40x40 pixels in size.
Verify that interactive controls have at least 5 pixels of spacing between them.
Visual Studio UX Guidelines: Evaluation Tools 327

2015 Visual Studio User Experience Guidelines RC Preview

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

2015 Visual Studio User Experience Guidelines RC Preview

Uploaded by

Copyright:

Available Formats

Visual Studio User Experience Guidelines

About these guidelines

Sections and topics

UX Essentials: Best practices, Anti-patterns,

Layout: Dialog layout

and Dev14 UX principles

Notifications and Progress: Notification systems,

Fonts and Formatting: The environment font

HDPI displays, Validating for HDPI displays, and

The VSColor service, Shared colors, Creating new color

Addressing DPI issues

tokens, Color value reference, Choosing High Contrast

11. Accessibility: Accessibility

colors, Using themed controls, Exposing colors for end

12. Animations: Animation fundamentals

4. Images and Icons: Image use in Visual Studio,

UI Text and Help: UI text and terminology,

10. HDPI Requirements: Requirements for supporting

Colors and Styling: Using color in Visual Studio,

users, and Daytona and web UI

Progress indicators, Infobars, and Error validation

Interaction Patterns: Visual Studio patterns overview,

and Animation patterns

Visual Studio User Experience Guidelines

UX Essentials: Best practices

Be consistent within the Visual Studio environment.

Use the environment service for fonts and colors.

4. Design from a user-centric perspective.

2 Visual Studio UX Guidelines: UX Essentials

Required fields/settings shown in error state by default

Example: Manifest Designer declarations

Multiple clicks to dismiss UI

Incorrect: forcing the user to read explanatory text before

The correct design for this situation would be to follow the

Correct: as designed, video links should display a tooltip with

4 Visual Studio UX Guidelines: UX Essentials

Using command bars for settings

Figure B: Better, but still an anti-pattern

Figure C: Correct use of Visual Studio pattern

Visual Studio UX Guidelines: UX Essentials 5

Underlining used as a group label, not a hyperlink

Clicking on a check box results in a pop-up dialog

6 Visual Studio UX Guidelines: UX Essentials

Using 'Click here' or 'Click here' for links

Visual Studio UX Guidelines: UX Essentials 7

UX Essentials: Dev14 UX principles

Be fast and fluid

Be true to the capabilities of hardware, software, and services.

Do more with less

Make the experience great at something, not mediocre at lots of things.

8 Visual Studio UX Guidelines: UX Essentials

2: Fonts and Formatting

Visual Studio User Experience Guidelines

Fonts and Formatting: The environment font

Editor font customization and resizing

Accessing the environment font

(Replace Microsoft.VisualStudio.Shell.11.0 with the current version of the MPF dll.)

Formatting (scaling/bolding) reference

375% Environment font + Light

Visual Studio UX Guidelines: Fonts and Formatting 11

310% Environment font + Light

200% Environment font + Semilight

155% Environment font

122% Environment font