Styling: Add more semantic color slots

common/changes/@uifabric/styling/phkuo-glamor_2017-05-31-22-58.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@uifabric/styling",
+      "comment": "add more semantic color slots",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@uifabric/styling",
+  "email": "[email protected]"
+}

packages/office-ui-fabric-react/src/components/Toggle/Toggle.styles.ts

@@ -13,11 +13,11 @@ export const getStyles = memoizeFunction((
 ): IToggleStyles => {
   const { semanticColors } = theme;
   const pillUncheckedBackground = semanticColors.bodyBackground;
-  const pillCheckedBackground = semanticColors.inputBackgroundSelected;
-  const pillCheckedHoveredBackground = semanticColors.inputBackgroundSelectedHovered;
+  const pillCheckedBackground = semanticColors.inputBackgroundChecked;
+  const pillCheckedHoveredBackground = semanticColors.inputBackgroundCheckedHovered;
   const pillCheckedDisabledBackground = semanticColors.disabledText;
   const thumbBackground = semanticColors.inputBorderHovered;
-  const thumbCheckedBackground = semanticColors.inputForegroundSelected;
+  const thumbCheckedBackground = semanticColors.inputForegroundChecked;
   const thumbDisabledBackground = semanticColors.disabledText;
   const thumbCheckedDisabledBackground = semanticColors.disabledBackground;
   const pillBorderColor = semanticColors.inputBorder;

packages/styling/src/interfaces/ISemanticColors.ts

@@ -1,31 +1,147 @@
 /**
+ *
  * The collection of semantic slots for colors used in themes.
- * See documentation [todo]
- */
+
+Naming Convention 
+The name of a semantic slot can quickly tell you how it’s meant to be used. It generally follows this format: 
+[category name][element name][checked state][hovered/pressed/disabled state]  
+[category name] – The “family” that this slot belongs to. 
+[element name] – The name of the thing being targeted, such as the background or border. 
+[checked state] – Whether the thing is checked. We assume things are unchecked by default, so no need to specify the unchecked state.
+(We used “checked” to refer to anything that is on, selected, toggled, highlighted, emphasized, etc.) 
+[hovered/pressed/disabled state] – One of these states, if applicable. Each of these states are mutually exclusive.
+Pressed styles overwrite hovered styles, and disabled elements cannot be hovered or pressed.   
+
+Base/Body
+A basic set of slots that provide many default body styles, such as text, subtext, disabled colors, error text, and so on.
+If a category doesn't provide the slot you're looking for, use one from this category.
+For example, the placeholder text on a text input field has no corresponding slot in its category,
+so you'd use the bodySubtextColor from this category. 
+
+Input Controls 
+This category contains input components commonly used to denote state, including radio buttons,
+check boxes, toggle switches, sliders, progress bars, and more. 
+
+Menus 
+Any kind of popup menus uses this category. 
+
+Lists 
+Lists differ from menus in that they are designed to show infinite amounts of items, often scroll,
+and have a large and complex interaction surface.
+This category covers all kinds of lists, whether they're typical one-item-per-row lists (like DetailsList) or ones with a tiled layout.
+
+*/
 export interface ISemanticColors {
+  /* ANY ADDITIONS/REMOVALS HERE MUST ALSO BE MADE TO \packages\styling\src\utilities\theme.ts:_makeSemanticColorsFromPalette() */
+
   /**
-   * ANY ADDITIONS/REMOVALS HERE MUST ALSO BE MADE TO \packages\styling\src\utilities\theme.ts:_makeSemanticColorsFromPalette()
+   * The default color for backgrounds.
    */
-
-  // Base slots defining universal colors
   bodyBackground?: string;
+  /**
+   * The default color for text.
+   */
   bodyText?: string;
+  /**
+   * De-emphasized text; e.g. metadata, captions, placeholder text.
+   */
   bodySubtext?: string;
+  /**
+   * Divider lines; e.g. lines that separate sections in a menu, an <HR> element.
+   */
+  bodyDivider?: string;
 
+  /**
+   * The default color for backgrounds of disabled controls; e.g. disabled text field.
+   */
   disabledBackground?: string;
+  /**
+   * The default color for disabled text; e.g. user input inside a disabled text field.
+   */
   disabledText?: string;
+  /**
+   * Disabled de-emphasized text; e.g. placeholder text inside disabled input field.
+   */
   disabledSubtext?: string;
 
+  /**
+   * The color of the outline around focused controls that don't already have a border; e.g. menu items
+   */
   focusBorder?: string;
 
   // Invariants - slots that rarely change color theme-to-theme because the color has meaning
+  /**
+   * The background for errors, if necessary, or highlighting the section of the page where the error is present.
+   */
   errorBackground?: string;
+  /**
+   * The default color of error text.
+   */
   errorText?: string;
 
   // Input controls slots (text fields, checkboxes, radios...)
+  /**
+   * The border of an input control in its resting, unchecked state; e.g. the box of an unchecked checkbox.
+   */
   inputBorder?: string;
+  /**
+   * The border color of a hovered input control.
+   */
   inputBorderHovered?: string;
-  inputBackgroundSelected?: string;
-  inputBackgroundSelectedHovered?: string;
-  inputForegroundSelected?: string;
+  /**
+   * The background of a checked control; e.g. checked radio button's dot, checked toggle's background.
+   */
+  inputBackgroundChecked?: string;
+  /**
+   * The background of a checked and hovered control; e.g. checked checkbox's background color on hover.
+   */
+  inputBackgroundCheckedHovered?: string;
+  /**
+   * The foreground of a checked control; e.g. checked checkbox's checkmark color, checked toggle's thumb color, radio button's background color around the dot.
+   */
+  inputForegroundChecked?: string;
+  /**
+   * The alternate focus border color for elements that already have a border; e.g. text field borders on focus.
+   */
+  inputFocusBorderAlt?: string;
+
+  // Menus, popups, etc
+  /**
+   * The background of a hovered menu item.
+   */
+  menuItemBackgroundHovered?: string;
+  /**
+   * The background of checked menu item; e.g. a menu item whose submenu is open, a selected dropdown item.
+   */
+  menuItemBackgroundChecked?: string;
+  /**
+   * The default colors of icons in menus.
+   */
+  menuIcon?: string;
+  /**
+   * The headers in menus that denote title of a section.
+   */
+  menuHeader?: string;
+
+  // Lists
+  /**
+   * The background color for the entire list.
+   */
+  listBackground?: string;
+  /**
+   * The default text color for list item titles and text in column fields.
+   */
+  listTextColor?: string;
+  /**
+   * The background color of a hovered list item.
+   */
+  listItemBackgroundHovered?: string;
+  /**
+   * The background color of a checked list item.
+   */
+  listItemBackgroundChecked?: string;
+  /**
+   * The background color of a checked and hovered list item.
+   */
+  listItemBackgroundCheckedHovered?: string;
 }

packages/styling/src/utilities/theme.ts

@@ -44,6 +44,7 @@ function _makeSemanticColorsFromPalette(p: IPalette): ISemanticColors {
     bodyBackground: p.white,
     bodyText: p.neutralPrimary,
     bodySubtext: p.neutralSecondary,
+    bodyDivider: p.neutralLight,
 
     disabledBackground: p.neutralLighter,
     disabledText: p.neutralTertiaryAlt,
@@ -56,8 +57,20 @@ function _makeSemanticColorsFromPalette(p: IPalette): ISemanticColors {
 
     inputBorder: p.neutralTertiary,
     inputBorderHovered: p.neutralPrimary,
-    inputBackgroundSelected: p.themePrimary,
-    inputBackgroundSelectedHovered: p.themeDarkAlt,
-    inputForegroundSelected: p.white
+    inputBackgroundChecked: p.themePrimary,
+    inputBackgroundCheckedHovered: p.themeDarkAlt,
+    inputForegroundChecked: p.white,
+    inputFocusBorderAlt: p.themePrimary,
+
+    menuItemBackgroundHovered: p.neutralLighter,
+    menuItemBackgroundChecked: p.neutralQuaternaryAlt,
+    menuIcon: p.themePrimary,
+    menuHeader: p.themePrimary,
+
+    listBackground: p.white,
+    listTextColor: p.neutralPrimary,
+    listItemBackgroundHovered: p.neutralLighter,
+    listItemBackgroundChecked: p.neutralQuaternary,
+    listItemBackgroundCheckedHovered: p.neutralQuaternaryAlt
   };
 }