2015 visual studio user experience guidelines rc preview

7/24/2019 2015 Visual Studio User Experience Guidelines RC Preview

1/328

Visual Studio User Experience Guidelines2015 RC PREVIEW

MICROSOFT V ISUAL STUDIO PARTNER PREVIEW COPY. SUBJECT TO CHANGE.

QUESTIONS OR FEEDBACK? CONTACT US AT [email protected]


2/328

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: TheWindows User Experience Interaction Guidelinesare 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.

Thepatterns and guides for Windows Store appsare a reference for emerging patterns that may be used in some

instances within Visual Studio.

About these guidelinesThese 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 thatallow you to write code for solutions that integrate into the Visual Studio IDE, use theVisual Studio SDK.

Sections and topics

1. UX Essentials:Best practices,Anti-patterns,

andDev14 UX principles

2. Fonts and Formatting:The environment font

andText style

3. Colors and Styling:Using color in Visual Studio,

The VSColor service,Shared colors,Creating new color

tokens,Color value reference,Choosing High Contrastcolors,Using themed controls,Exposing colors for end

users,andDaytona and web UI

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

Visual Language Dictionary,Icon design,Using color

in images,andIcon theming and inversion

5. Menus and Commands:Command usage,

Naming commands,andAccess and shortcut keys

6. UI Text and Help:UI text and terminology,

Error messages,andAccessing Help

7.

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,andTree views),On-object UI and

peeking,Selection models,Persistence and saving

settings,andTouch input

8. Layout:Dialog layout

9. Notifications and Progress:Notification systems,

Progress indicators,Infobars,andError validation

10. HDPI Requirements:Requirements for supporting

HDPI displays,Validating for HDPI displays,and

Addressing DPI issues

11.

Accessibility:Accessibility12. Animations:Animation fundamentals

andAnimation patterns

13. World Readiness:World readiness

14. Evaluation Tools:Craftsmanship checklist
http://go.microsoft.com/fwlink/?LinkId=136544http://go.microsoft.com/fwlink/?LinkId=136544http://go.microsoft.com/fwlink/?LinkId=136544http://msdn.microsoft.com/en-US/windows/apps/dn439965http://msdn.microsoft.com/en-US/windows/apps/dn439965http://msdn.microsoft.com/en-US/windows/apps/dn439965https://msdn.microsoft.com/en-us/library/bb166441(v=vs.140).aspxhttps://msdn.microsoft.com/en-us/library/bb166441(v=vs.140).aspxhttps://msdn.microsoft.com/en-us/library/bb166441(v=vs.140).aspxhttps://msdn.microsoft.com/en-us/library/bb166441(v=vs.140).aspxhttp://msdn.microsoft.com/en-US/windows/apps/dn439965http://go.microsoft.com/fwlink/?LinkId=136544


3/328

1: UX Essentials





4/328

2Visual Studio UX Guidelines:UX Essentials

EARLY PARTNER PREVIEW OF 2015 GUIDELINES. SUBJECT TO CHANGE. FOR QUESTIONS OR FEEDBACK, EMAIL [email protected].

UX Essentials: Best practices

Screen resolutionMinimum resolutionThe minimum resolution for Visual Studio Dev14 is 1280x1024. This means that it is possibleto 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 displaysUI 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 principles1. 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.

FollowVisual Studio design principlesfor 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)


5/328

Visual Studio UX Guidelines:UX Essentials 3


UX Essentials: Anti-patternsVisual 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, theUxBoardis always available to answer

your questions.

Required fields/settings shown in error state by defaultFeature 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 solutionAs 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 declarationsAdding 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 clunkycontrol.

ResultThe 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.

AlternativesBetter 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.
mailto:[email protected]:[email protected]:[email protected]:[email protected]


6/328



Multiple clicks to dismiss UIFeature team goalDont allow the user to dismiss the UI without first seeing the

explanation text.

Anti-pattern

The team inserting video links into various places within VisualStudio 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.

ResultInstead 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.

AlternativesThe 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.

Incorrect: forcing the user to read explanatory text before

dismissing UI is an anti-pattern within Visual Studio.

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.


7/328



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 Arepresents 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 switchingbetween four commands. This is the only situation in which commands in the toolbar are acceptable.


8/328



Control anti-patternsSome anti-patterns are simply incorrect usage or presentation of a control or group of controls.

Underlining used as a group label, not a hyperlinkUnderlining 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.


9/328



Hyperlink anti-patternsThe following example contains two anti-patterns.

1. The foreground turning red on hover means that the correct shared color from the font service is not being used.

2. 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.

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 abouthow to create a new project.

Good:How do I create a new project?

Both the color choice and wording of this hyperlink are Visual Studio anti-patterns.


10/328



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.


11/328

2: Fonts and Formatting





12/328

10Visual Studio UX Guidelines:Fonts and Formatting


Fonts and Formatting: The environment fontAll fonts within Visual Studio must be exposed to the user for customization. This is primarily done through the Fonts and

Colorspage in the Tools > Optionsdialog. The three main categories of font settings are:

Environment fontthe 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 editorelements that surface in the code editor and other text-based editors can be customized in the Text

Editor settings in Tools > Options.

Specific collectionsdesigner 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 resizingUsers 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. For code text in the editor, resize with the code text font setting and respond to the editor texts zoom level.

2. 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::GetDialogFontafter querying the interface from the SID_SUIHostLocale service. For Windows Presentation Foundation (WPF), derive your

dialog window class from the shell's DialogWindowclass instead of WPF's Windowclass.

In XAML, the code looks like this:

Code behind:

internalpartialclassWebConfigModificationWindow : DialogWindow{}

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


13/328

Visual Studio UX Guidelines:Fonts and Formatting 11


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 = newMyWindow();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 FontFamilyand FontSizeon 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:

Formatting (scaling/bolding) referenceSome 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 Lightor Semilight).

Note:Before you apply formatting, ensure that you are following the guidance found inText 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 + LightAppears 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: 375Percent Scaling

Label: 375 PercentScaling


14/328



310% Environment font + LightAppears as:28 pt Segoe UI Light

Use for:large signature dialog titles, main heading in reports

Procedural code:Where "textBlock" is a previously defined TextBlock and "label" is a previously defined Label:






200% Environment font + SemilightAppears as:18 pt Segoe UI Semilight

Use for: subheadings, titles in small and medium dialogs




XAML: Set the style of the TextBlock or Label as shown:



155% Environment fontAppears as:14 pt Segoe UI

Use for:section headings in document well UI or reports



label.SetResourceReference(Label.StyleProperty,

VsResourceKeys.LabelEnvironment155PercentFontSizeStyleKey);XAML:Set the style of the TextBlock or Label as shown:




15/328



122% Environment fontAppears as:11 pt Segoe UI

Use for:section headings in signature dialogs, top nodes in tree view, vertical tab navigation







Environment font + bold

Appears as:Bolded 9 pt Segoe UIUse for:Labels and subheads in signature dialogs, reports, and document well UI

Procedural code: Where "textBlock" is a previously defined TextBlock and "label" is a previously defined Label:

textBlock.SetResourceReference(TextBlock.StyleProperty,

VsResourceKeys.TextBlockEnvironmentBoldStyleKey);

label.SetResourceReference(Label.StyleProperty,

VsResourceKeys.LabelEnvironmentBoldStyleKey);

XAML: Set the style of the TextBlock or Label as shown:

Bold TextBlock

Bold Label


16/328



Localizable stylesIn 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 FontChangedevent. 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:

privatevoidForm1_FontChanged(objectsender, System.EventArgs e){

SetFontStyles();}

//////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 ...).///protectedvoidSetFontStyles(){

SetFontStyles(this, this, this.Font);}

protectedstaticvoidSetFontStyles(Control topControl, Control parent, Font referenceFont){

foreach(Control c inparent.Controls)

{ if(c.Controls != null&& c.Controls.Count > 0) {SetFontStyles(topControl, c, referenceFont);

}if(c.Font != topControl.Font) {

c.Font = newFont(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 IUIServiceand the

FontChangedevent will never fire. Hooking FontChangedwill allow dialogs to dynamically pick up the new font even if

the dialog is already open.


17/328



Testing the environment fontTo ensure that your UI is using the environment font and respects the size settings, open Tools > Options > Environment

> Fonts and Colorsand 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 withserifs (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.


18/328



Fonts and Formatting: Text styleText style refers to font size, weight, and casing. This topic is about design. For implementation guidance,

seeThe environment font.

Text casing

All capsDo not use all caps for titles or labels in Visual Studio.

All lowercaseDo not use all lowercase for titles or labels in Visual Studio.

Sentence and title caseText 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 itemsButtons

Table labels

Column headers

Tooltips

Use sentence case for:

Labels

Check boxes

Radio buttons

List box itemsStatus 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

proper adjective, or if the words have equal weight

Cross-Reference, Pre-Microsoft Software, Read/Write

Access, Run-Time


19/328



Lowercase Examples

The second word in a compound word if it is another part of

speech or a participle modifying the first word

How-to, Take-off

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

verb phrase

into, onto, as for, out of, on top of

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 formattingDefault text formatting in Visual Studio 2013 is controlled by anenvironment 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

toThe environment font.

Bold textBold 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 italicorbolded 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

o To call attention to a specific area

o To offer relief from the standard dark gray/black environment text color


20/328



Color in headings should leverage existing Visual Studio brand colors, primarily the main purple, #FF68217A.

When using color in headings, you must adhere to theWindows color guidelines,including contrast ratio and

other accessibility considerations.

Font sizeVisual 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 beimportant, 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 inThe environment font.

Headline 1: Environment font x 375% + Light

AaBbCcXxYyZzUsage:Rare. Uniquebranded UI only.

Do:

- Use sentence

case

- Always use Light

weight

Do not:

-

Use for UI otherthan signature UI

such as Start

Page

- Bold, italic, or

bold italic

- Use for body

text

- Use in tool

windows

In comps, appears as 34pt Segoe UI Light.

Spec as: Environment font x 375% + Light.

Visual example:

Currently not used. May be used in the Start Page.
http://msdn.microsoft.com/en-us/library/dn742482.aspxhttp://msdn.microsoft.com/en-us/library/dn742482.aspxhttp://msdn.microsoft.com/en-us/library/dn742482.aspxhttp://msdn.microsoft.com/en-us/library/dn742482.aspx


21/328



Headline 2: Environment font x 310% + Light

AaBbCcXxYyZzUsage:

- Larger heading in

signature dialogs

- Main reportheading

Do:

- Use sentence case

- Always use Light

weight

Do not:

- Use for UI other

than signature UI

such as Start Page

-

Bold, italic, or bolditalic

- Use for body text

- Use in tool

windows

In comps, appears as 28pt Segoe UI Light.

Spec as: Environment font x 310% + Light.

Visual example:

Headline 3: Environment font x 200% + Semilight

AaBbCcXxYyZzUsage:

- Subheadings

-

Titles in small andmedium dialogs

Do:

- Use sentence case

- Always use

Semilight weight

Do not:

- Bold, italic, or bold

italic

- Use for body text

-

Use in toolwindows

In comps, appears as 18 pt Segoe UI Semilight.

Spec as: Environment font x 200% + Semilight.

Visual example:


22/328



Headline 4: Environment font x 155%

AaBbCcXxYyZz

Usage:

- Section headings in

document well UI

- Reports

Do:

- Use sentence case

Do not:

- Bold, italic, or bold

italic

- Use for body text

- Use in standard VS

controls

- Use in tool

windows

In comps, appears as 14 pt Segoe UI.

Spec as: Environment font x 155%.

Visual example:

Headline 5: Environment font x 122%AaBbCcXxYyZz

Usage:

- Section headings

in signature

dialogs

- Top nodes in tree

view

- Vertical tab

navigation

Do:

- Use sentence

case

Do not:

- Bold, italic, or

bold italic

- Use for body text

- Use in standard

VS controls

- Use in tool

windows


Spec as: Environment font x 122%.

Visual example:


23/328



Headline 6: Environment font + BoldAaBbCcXxYyZz

Usage:

- Labels and

subheads in

signature dialogs,

reports, and

document well UI

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

In comps, appears as bolded 9 pt Segoe UI.

Spec as: Environment font + Bold.

Visual example:

Body: Environment fontAaBbCcXxYyZz

Usage:

All other text

Do:

- Use sentence

case

Do not:

- Italic or bold

italic


Spec as: Environment font.

Visual example:


24/328



Padding and spacingHeadings 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
http://msdn.microsoft.com/en-us/library/windows/desktop/dn742483(v=vs.85).aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/dn742483(v=vs.85).aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/dn742478(v=vs.85).aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/dn742478(v=vs.85).aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/dn742478(v=vs.85).aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/dn742483(v=vs.85).aspx


25/328

3: Colors and Styling





26/328

24Visual Studio UX Guidelines:Colors and Styling


Colors and Styling: Using color in Visual Studio

Color is an important element in most user interfaces, including Visual Studio. According to theWindows 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. Understand the different services and systems used to define colors in Visual Studio.

2. Select the correct option for a given element.

3.

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 theVSColor serviceand will either have to implement your own theme-switching method or your UI

might look inconsistent in Visual Studio.
http://msdn.microsoft.com/library/windows/desktop/dn688964.aspxhttp://msdn.microsoft.com/library/windows/desktop/dn688964.aspxhttp://msdn.microsoft.com/library/windows/desktop/dn688964.aspxhttp://msdn.microsoft.com/library/windows/desktop/dn688964.aspx


27/328

Visual Studio UX Guidelines:Colors and Styling 25


Methods for assigning color to Visual Studio interface elementsChoose the method best suited to your UI elements:

Your UI Method What are they?

You have embedded or standalone

dialog boxes.

System colors System names that allow the operating system to define the

color and appearance of the UI elements, such as for common

dialog controls

You have custom UI that you want tobe consistent with the overall VS

environment and you have UI

elements that match the category

and semantic meaning of the shared

tokens.

Common shared colors Existing predefined color token names for specific UI elements

You have an individual feature or

group of features and there is no

shared color for similar elements.

Custom colors Color token names that are specific to an area and not meant

to be shared with other UI

You want to allow the end user to

customize UI or content (for example,

for text editors or specializeddesigner windows).

End-user customization

(Tools > Options dialog)

Settings defined in the Fonts and Colors page of the Tools >

Options dialog or a specialized page specific to one UI feature

You have UI that is authored in

HTML.

Daytona Allows UI authored in HTML to access the color and font service

Visual Studio themesVisual 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 themedrop-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,

seeChoosing High Contrast colors.


28/328



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. Use a named color token that has been predefined for the environment. See theShared colorstopic 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.

2. Design your own set of colors, give each color a token name, and add these definitions to your own theme color

XML file. TheColor value referencetopic can assist you in choosing colors, and theCreating new color tokens

topic will tell you how to add the colors to the service.

How the service worksThe 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


29/328



Accessing the serviceThere 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 COLORREFof the colors. The service/interface is:

IVsUIShell2::GetVSSysColorEx(VSSYSCOLOR dwSysColIndex, DWORD *pdwRGBval)

In the file VSShell80.idl, the enumeration __VSSYSCOLOREXhas shell color constants. To use it, pass in as the index value

either one of the values from theenum __VSSYSCOLOREXdocumented 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_SYSCOLORCHANGEand WM_THEMECHANGEDmessages.

// 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.GetThemedColorinstead 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)

{ //getIVSUIShell2IVsUIShell2 uiShell2 = Package.GetService(typeof(SVsUIShell)) as IVsUIShell2;Debug.Assert (uiShell2 != null, "failed to get IVsUIShell2");

if(uiShell2 != null){

//get the COLORREF structureuintwin32Color;uiShell.GetVSSysColorEx(VSSYSCOLOREX.VSCOLOR_SMARTTAG_HOVER_FILL, outwin32Color);

//translate it to a managed Color structureColor myColor = ColorTranslator.FromWin32((int)win32Color);

//use ite.Graphics.FillRectangle( newSolidBrush(myColor), 0, 0, 100, 100);

}

}

If you are working in Visual Basic, use:

DimmyColor AsColor = ColorTranslator.FromWin32((Integer)win32Color)
http://msdn.microsoft.com/en-us/library/microsoft.visualstudio.shell.interop.__vssyscolorex.aspxhttp://msdn.microsoft.com/en-us/library/microsoft.visualstudio.shell.interop.__vssyscolorex.aspxhttp://msdn.microsoft.com/en-us/library/microsoft.visualstudio.shell.interop.__vssyscolorex.aspxhttp://msdn.microsoft.com/en-us/library/microsoft.visualstudio.shell.interop.__vssyscolorex.aspx


30/328



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.

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 compiledas 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 SelectedItemcolor:

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_THEMECHANGEDor

WM_SYSCOLORCHANGEmessages are broadcast to subscribers of IVsShell.AdviseBroadcastMessages. The class

VSColorThemeprovides a way to be notified of the change by listening to the ThemeChangedevent.

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.GetThemedColorin Visual Studio 2012. Code that uses GetVSSysColorExwill

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, youwill not be able to access new colors defined in

Visual Studio 2012 or your VSPackage.


31/328



Helper classes and methods for managed codeFor 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.VsColorsclass in MPF include GetThemedGDIColor()and GetThemedWPFColor(). Those

helper methods return the color value of a theme entry as System.Drawing.Coloror 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);

/// ///Gets a System.Drawing.Color value from the current theme for the given color key./// /// The IVsUIShell5 service, used to get the color's value./// The key to find the color for./// The current theme's value of the named color.

public staticSystem.Drawing.Color GetThemedGDIColor(thisIVsUIShell5 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 ABGRreturn System.Drawing.Color.FromArgb(colorComponents[3], colorComponents[0],

colorComponents[1], colorComponents[2]);}

private static byte[] GetThemedColorRgba(IVsUIShell5 vsUIShell, ThemeResourceKeythemeResourceKey){

Guid category = themeResourceKey.Category;__THEMEDCOLORTYPE colorType = __THEMEDCOLORTYPE.TCT_Foregroundif(themeResourceKey.KeyType == ThemeResourceKeyType.BackgroundColor ||

themeResourceKey.KeyType == ThemeResourceKeyType.BackgroundBrush){

colorType = __THEMEDCOLORTYPE.TCT_Background;}

// This call will throw an exception if the color is not founduint rgbaColor = vsUIShell.GetThemedColor(ref category, themeResourceKey.Name,

(uint)colorType);return BitConverter.GetBytes(rgbaColor);

}

public staticSystem.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]);}


32/328



The class can also be used to obtain VSCOLOR identifiers for a given WPF color resource key, or vice versa.

public static stringGetColorBaseKey(intvsSysColor);

public static boolTryGetColorIDFromBaseKey(stringbaseKey, out intvsSysColor);

The methods of VsColorsclass 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.VSThemeColorclass, 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 ThemeChangedevent

to add a new handler, and use the GetThemedColor()method to obtain color values for the ThemeResourceKeysof

interest. A sample code could look like this:

publicMyWindowPanel()

{

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 voidRefreshColors(){

this.BackColor = VSColorTheme.GetThemedColor(EnvironmentColors.ToolWindowBackgroundColorKey);

this.ForeColor = VSColorTheme.GetThemedColor(EnvironmentColors.ToolWindowTextColorKey);

}

protected override voidDispose(booldisposing)

{

if(disposing)

{

VSColorTheme.ThemeChanged -= this.VSColorTheme_ThemeChanged;

base.Dispose(disposing);

}

}


33/328



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, seeThe 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 todisplay 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!


34/328



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 VisualStudio 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.


35/328



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

for anything that you dont want to always match the menu title.

in any background/foreground combination other than specified.

State Component Element Token name: Category.Color

Default

Menu title

Menu title with glyph

Background None

Foreground (Text) Environment.CommandBarTextActive

Foreground (Glyph) Environment.CommandBarMenuGlyph

Border None

Hover

Menu title


BackgroundEnvironment.CommandBarMouseOverBackgroundBegin

Gradient stops for this token not used in themed UI.Foreground (Text) Environment.CommandBarTextHover

Foreground (Glyph) Environment.CommandBarMenuMouseOverGlyph

Border Environment.CommandBarBorder

Pressed

Menu title


BackgroundEnvironment.CommandBarMenuBackgroundGradientBeginGradient stops for this token not used in themed UI.


Foreground (Glyph) Environment.CommandBarMenuMouseDownGlyph

Border Environment.CommandBarMenuBorder

Disabled


Background None

Foreground (Text) Environment.CommandBarTextInactive

Foreground (Glyph) Environment.CommandBarTextInactive

Border None


36/328



Menu

An individual menu itemconsists 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

for any drop-down list that occurs in

another context.

in any background/foreground

combination other than specified.


Default

Menu

BackgroundEnvironment.CommandBarMenuBackgroundGradienBeginGradient stops for this token not used in themed UI.


Foreground

(Submenu glyph) Environment.CommandBarMenuSubmenuGlyph

Border Environment.CommandBarMenuBorder

Icon channel

backgroundEnvironment.CommandBarMenuIconBackground

Separator Environment.CommandBarMenuSeparator

Shadow Environment.DropShadowBackground

Checked

Selected

Checkmark Environment.CommandBarCheckBox

Checkmark

backgroundEnvironment.CommandBarSelectedIcon

Icon background Environment.CommandBarSelectedIcon border Environment.CommandBarSelectedBorder

Hover

Menu item

Background Environment.CommandBarMenuItemMouseOver

Foreground (Text) Environment.CommandBarMenuItemMouseOver

Foreground

(Submenu glyph)

Environment.CommandBarMenuMouseOverSubmenuGyph


37/328




Hover

Checked

Selected

Checkmark Environment.CommandBarCheckBoxMouseOver

Checkmark

backgroundEnvironment.CommandBarHoverOverSelectedIcon

Icon background Environment.CommandBarHoverOverSelected

Icon borderEnvironment.CommandBarHoverOverSelectedIconorder

Disabled

Menu item


Foreground

(Submenu glyph)Environment.CommandBarMenuSubmenuGlyph

Checked

Checkmark Environment.CommandBarCheckBoxDisabled

Checkmark

backgroundEnvironment.CommandBarSelectedIconDisabled


38/328



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

in places where you need an embedded command

bar but are unable to use the standard Visual

Studio command bar implementation.

Do not use

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

in places where you need an embedded command

bar but are unable to use the standard Visual

Studio command bar implementation.

Do not use

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 Token name: Category.Color

Default

(No other states)Background

Environment.CommandBarGradientBeginGradient stops for this token not used in themed UI.

Border Environment.CommandBarToolBarBorderDrag handle Environment.CommandBarDragHandle

SeparatorEnvironment.CommandBarToolBarSeparator

Environment.CommandBarToolBarSeparatorHighlight


39/328



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

for controls that have their own token names.

in any background/foreground combination other than specified.


Default

Standard

Background N/A (inherits from command bar background)


Border N/A

Selected

Background Environment.CommandBarSelected

Foreground (Text) Environment.CommandBarTextSelected

Border Environment.CommandBarSelectedBorder

Hover and

keyboard

focusedStandard

BackgroundEnvironment.CommandBarMouseOverBackgroundBegin

Gradient stops for this token not used in themed UI.Foreground (Text) Environment.CommandBarTextHover


Selected

Background Environment.CommandBarHoverOverSelected

Foreground (Text) Environment.CommandBarTextHoverOverSelected

Border Environment.CommandBarHoverOverSelectedIconBorder

Pressed

Standard

BackgroundEnvironment.CommandBarMouseDownBackgroundBeginGradient stops and values available, but not used in themed UI.

Foreground (Text) Environment.CommandBarTextMouseDown


Disabled

Standard

Background N/A (inherits from command bar background)


Border N/A

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.


40/328



State Component Element Token Name: Category.Color

Default

Input field

Background Environment.ComboBoxBackground

Foreground (Text) Environment.ComboBoxText

Border Environment.ComboBoxBorder

Separator No separator

Drop-down button

Background N/A (inherits)

Foreground (Glyph) Environment.ComboBoxGlyph

Drop-down list

Background Environment.ComboBoxPopupBackgroundBeginGradient stops for this token not used in themed UI.

Foreground (Text) Environment.ComboBoxItemText

Border Environment.ComboBoxPopupBorder

Hover

Input fieldBackground

Environment.ComboBoxMouseOverBackgroundBeginGradient stops for this token not used in themed UI.

Foreground (Text) Environment.ComboBoxMouseOverText

Border Environment.ComboBoxMouseOverBorder

Separator Environment.ComboBoxMouseOverSeparator

Drop-down button

Background Environment.ComboBoxButtonMouseOverBackground

Foreground (Glyph) Environment.ComboBoxMouseOverGlyph

Drop-down list

Drop-down list

Background

(Outside)

Environment.ComboBoxMouseOverBackgroundBeginGradient stops for this token not used in themed UI.

Background (Item) Environment.ComboBoxItemMouseOverBackground

Foreground (Text) Environment.ComboBoxItemMouseOverText

Border (Outside) Environment.ComboBoxMouseOverBorder

Focused

Input field

Background Environment.ComboBoxFocusedBackground

Foreground (Text) Environment.ComboBoxFocusedText

Border Environment.ComboBoxFocusedBorder

Separator Environment.ComboBoxFocusedButtonSeparator

Drop-down button

Background Environment.ComboBoxFocusedButtonBackground

Foreground (Glyph) Environment.ComboBoxFocusedGlyph

Pressed

Input field

Background Environment.ComboBoxMouseDownBackground

Foreground (Text) Environment.ComboBoxMouseDownText

Border Environment.ComboBoxMouseDownBorder

Separator Environment.ComboBoxMouseDownSeparator

Drop-down button

Background Environment.ComboBoxButtonMouseDownBackground

Foreground (Glyph)Environment.ComboBoxMouseDownGlyph

Disabled

Input field

Background Environment.ComboBoxDisabledBackground

Foreground (Text) Environment.ComboBoxDisabledText

Border Environment.ComboBoxDisabledBorder


Drop-down button

Background N/A

Foreground (Glyph) Environment.ComboBoxDisabledGlyph


41/328



Drop-down

Use

when you are creating custom drop-down list controls.

Do not use

for anything that is not similar to a drop-down list.

for combo boxes or split buttons.


Default

Selection field

Background Environment.DropDownBackground

Foreground (Text) Environment.DropDownText

Border Environment.DropDownBorder


Drop-down button

Background None

Foreground (Glyph) Environment.DropDownGlyph

Drop-down list

BackgroundEnvironment.DropDownPopupBackgroundBeginGradient stops for this token not used in themed UI.

Foreground (Text) Environment.ComboBoxItemText

Border Environment.DropDownPopupBorder

Shadow Environment.DropShadowBackground

Hover

Selection field

BackgroundEnvironment.DropDownMouseOverBackgroundBeginGradient stops for this token not used in themed UI.

Border Environment.DropDownMouseOverBorder

Separator Environment.DropDownButtonMouseOverSeparator

Background Environment.DropDownButtonMouseOverBackground

Drop-down button

Foreground (Glyph) Environment.DropDownMouseOverGlyph

Background

(Menu item)

Environment.ComboBoxItemMouseOverBackground

Drop-down list

Foreground (Text) Environment.ComboBoxItemMouseOverText

Border (outside) Environment.ComboBoxMouseOverBorder

Border (Menu item) Environment.ComboBoxItemMouseOverBorder

Pressed

Selection field

Background Environment.DropDownMouseDownBackground

Foreground (Text) Environment.DropDownMouseDownText

Border Environment.DropDownMouseDownBorder

Separator Environment.DropDownButtonMouseDownSeparator

Drop-down button

Background Environment.DropDownButtonMouseDownBackground

Foreground (Glyph) Environment.DropDownMouseDownGlyph


42/328



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

for other kinds of buttons. in any background/foreground combination other than specified.


Default Background None


Foreground (Glyph) Environment.CommandBarSplitButtonGlyph

Border N/A

Separator N/A

Hover Background Environment.CommandBarMouseOverBackgroundBeginGradient stops for this token not used in themed UI.

Foreground (Text) Environment.CommandBarTextHover

Foreground (Glyph) Environment.CommandBarSplitButtonMouseOverGlyph


Separator Environment.CommandBarSplitButtonSeparator

Background Environment.CommandBarMouseOverBackgroundBeginGradient stops for this token not used in themed UI.

Pressed Background Environment.CommandBarMouseDownBackgroundBeginGradient stops for this token not used in themed UI.

Foreground (Text) Environment.CommandBarTextMouseDown

Foreground (Glyph) Environment.CommandBarSplitButtonMouseDownGlyph


Separator N/A

Disabled Background N/A

Foreground (Text) Environment.ComboBoxItemTextInactive

Foreground (Glyph) Environment.CommandBarTextInactive

Border None

Separator N/A


43/328



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

for buttons that dont have similar functionality to a More options or Overflow button.


Default

More

options

Overflow

Background Environment.CommandBarOptionsBackground

Foreground (Glyph) Environment.CommandBarOptionsGlyph

Hover

More

options

Overflow

BackgroundEnvironment.CommandBarOptionsMouseOverBackgroundBeginGradient stops for this token not used in themed UI.

Foreground (Glyph) Environment.CommandBarOptionsMouseOverGlyph

Pressed

More

options

Overflow

BackgroundEnvironment.CommandBarOptionsMouseDownBackgroundBeginGradient stops for this token not used in themed UI.

Foreground (Glyph) Environment.CommandBarOptionsMouseDownGlyph


44/328



Document windowsThere 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 toColor

Value Referenceand use the hues to create your own token names.


45/328




Default Document: docked or floating Background Depends on document type

Foreground

(Text)Depends on document type

Border Environment.ToolWindowBorder

Frame: floating, focused

Background Environment.ToolWindowFloatingFrame

Foreground

(Text)Environment.ToolWindowFloatingFrame

Foreground

(Glyph)Environment.RaftedWindowButtonActiveGlyph

Border Environment.MainWindowActiveDefaultBorder

Border (Glyph)Environment.RaftedWindowButtonActiveBorderSet to transparent

Frame: floating, unfocused

Background Environment.ToolWindowFloatingFrameInactive

Foreground

(Text)Environment.ToolWindowFloatingFrameInactive

Foreground

(Glyph)Environment.RaftedWindowButtonInactiveGlyph

Border Environment.MainWindowInactiveBorder

Border (Glyph)Environment.RaftedWindowButtonInactiveBorderSet to transparent

Hover

Frame: floating, focused

Background

(Glyph)Environment.RaftedWindowButtonHoverActive

Foreground

(Glyph)Environment.RaftedWindowButtonHoverActiveGlyph

Border (Glyph) Environment.RaftedWindowButtonHoverActiveBorder

Frame: floating, unfocused

Background

(Glyph)Environment.RaftedWindowButtonHoverInactive

Foreground

(Glyph)Environment.RaftedWindowButtonHoverInactiveGlyph

Border (Glyph) Environment.RaftedWindowButtonHoverInactiveBorder

Pressed Background

(Glyph)Environment.RaftedWindowButtonDown

Foreground

(Glyph)Environment.RaftedWindowButtonDownGlyph

Border (Glyph) Environment.RaftedWindowButtonDownBorder


46/328



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 Referenceand use the hues to create your

own token names.

Selected tab

State Compone