Merge pull request #492 from dxc-technology/component-switch

Component switch documentation update

Author: aweell

contributing/assets/components/switch_images.xd

@@ -3,73 +3,93 @@
 Switch toggles are elements that can get two simple states, each of them has an impact on the system and it can be switched on or off, there are no more options.
 If the switch toggle is on one state, the action to change it will modify to value of the element to the contrary.
 
-The main difference to using a switch toggle instead of other components with a similar purpose like radio buttons or checkboxes are the immediate effect that they should take. This grants the users control on the application, changing preferences and configuration settings.
+## Usage
 
-With the use of switch toggle, it is not needed a submit button to do the appropriate action, because the action takes place at the moment that the switch is turned on or off.
+- Switch toggles should be used in place of radio buttons whenever the options are opposites of each other (i.e. yes/no, on/off, etc).
+- Whenever is possible stack the switch component vertically.
+- Switches have immediate effect over the application, changing preferences and configuration settings. Don't use a submit button.
+
+## States
 
-## Appereance
+Five different states are defined in the life cycle of the component: **unselected enabled**, **unselected focus**, **unselected disabled**, **selected enabled**, **selected focus** and **selected disabled**
 
-The appearance of the component should provide good visual feedback, making clear when the switch is on or off. To make a difference between states colors, shadows and fill properties can be used.
+![Switch component states](images/switch_states.png)
 
-A label can be linked with the component to indicate what action will perform when the change occurs. It should be descriptive and clear about what the component is doing or affecting.
+_Switch component states_
 
-## Modes
+## Anatomy
 
-Two main modes are represented within the component.
+![Switch component anatomy](images/switch_anatomy.png)
 
-Modes: **on** and **off**.
+1. Label
+2. Thumb
+3. Track
 
-![Switch modes](images/switch_modes.png)
+## Stacking
 
-## States
+![Switch stacking options](images/switch_stacking.png)
+
+_Switch stacking options_
+
+In some application the use of several switches based on the requirements could appear, that why we provide some indications in the case that the user needs to use stacked switches.
+
+## Label position
 
-Five different states are defined in the life cycle of the component: **normal**, **disabled**, **hovered** and **focused**.
+![Switch label position options example](images/switch_label_position.png)
 
-![Switch modes](images/switch_states.png)
+_Switch label position options example_
 
-## Design tokens
+| Position         | Description                                               |
+| :--------------- | :-------------------------------------------------------- |
+| **Label before** | Labels before the switch indicate what the switch is for  |
+| **Label after**  | Labels after the switch indicate the state of the switch  |
 
-| Tokens                                | Default value |
-| ------------------------------------- | ------------: |
-| `checkedTrackBackgroundColor`           |     #5f249f |
-| `disabledCheckedTrackBackgroundColor`   |     #D0BDDB |
-| `checkedthumbBackgroundColor`           |     #FFFFFF |
-| `uncheckedThumbBackgroundColor`         |     #FFFFFF |
-| `uncheckedTrackBackgroundColor`         |     #D9D9D9 |
-| `disabledUncheckedTrackBackgroundColor` |     #D9D9D9 + 0.12 opacity |
-| `fontColor`                             |     #000000 |
-| `disabledFontColor`                     |     #000000 + 0.12 opacity |
-| `focusColor`                            |     #005FCC |
 
 ## Design Specifications
 
-Schematics examples for the switch toggle component with all the variations.
 
-![Switch specifications](images/switch_specs.png)
+![Switch design specifications](images/switch_specs.png)
 
-In some application the use of several switches based on the requirments could appear, that why we provide some indications in the case that the user needs to use stacked or linear switches.
+_Switch design specifications_
 
-### Linear
 
-The text should have a margin of 16 pixels based on its position. If the text is after the switch, it should define the margin on the right side. Otherwise, if the label of the switch is before the component, the margin has to go on the left side.
+### Color
 
-![Switch linear structure](images/switch_linear.png)
+| Component token                           | Element                         | Core token          | Value     |
+| :---------------------------------------- | :------------------------------ | :------------------ | :-------- |
+| `labelFontColor`                          | Label                           | `color-black`       | #000000   |
+| `disabledLabelFontColor`                  | Label:disabled                  | `color-grey-400`    | #bfbfbf   |
+| `thumbBackgroundColor`                    | Thumb                           | `color-white`       | #ffffff   |
+| `focusThumbBorderColor`                   | Thumb:focus                     | `color-blue-600`    | #0095ff   |
+| `unselectedTrackBackgroundColor`          | Track unselected                | `color-grey-400`    | #bfbfbf   |
+| `selectedTrackBackgroundColor`            | Track selected                  | `color-purple-700`  | #5f249f   |
+| `disableudUnselectedTrackBackgroundColor` | Track:disabled unselected       | `color-grey-100`    | #f2f2f2   |
+| `disabledSelectedTrackBackgroundColor`    | Track:disabled selected         | `color-purple-100`  | #f2eafa   |
 
-### Stacked
 
-The spacing between stacked switches should be 24 pixels that is determining by the top/bottom margin of the switch component itself.
+### Typography
 
-![Switch stacked structure](images/switch_stacked.png)
+| Component token                           | Element                         | Core token            | Value        |
+| :---------------------------------------- | :------------------------------ | :-------------------- | :----------- |
+| `labelFontFamily`                         | Label                           | `font-family-sans`    | Open sans    |
+| `labelFontSize`                           | Label                           | `font-scale-02`       | 1rem / 16px  |
+| `labelFontWeight`                         | Label                           | `font-weight-regular` | 400          |
+| `labelFontStyle`                          | Label                           | `font-style-normal`   | normal       |
 
-#### Sizes
 
-| Property                   |         Value |
-| -------------------------- | ------------: |
-| Toggle bar                 |          36px |
-| Focused ripple             |       42x42px |
-| Toggle button              |       24x24px |
+### Size
 
-#### Margin
+| Component token                           | Element                         | Core token            | Value        |
+| :---------------------------------------- | :------------------------------ | :-------------------- | :----------- |
+| `thumbHeight`                             | Thumb                           | -                     | 24px         |
+| `thumbWidth`                              | Thumb                           | -                     | 24px         |
+| `trackHeight`                             | Track                           | -                     | 12px         |
+| `trackWidth`                              | Track                           | -                     | 60px         |
+| `focusHeight`                             | Focus indicator                 | -                     | 40px         |
+| `focusWidth`                              | Focus indicator                 | -                     | 40px         |
+
+
+### Margin
 
 margin | value
 -- | --
@@ -84,29 +104,21 @@ margin | value
 And also apply different values to each side of the component:
 `top` `bottom` `left` `right`
 
-#### Typography
-
-| Property                   |         Value |
-| -------------------------- | ------------: |
-| Font size (with text)      |        `16px` |
-| Font weight                |     `Regular` |
-
-#### Spacing
 
-| Property                   |         Value |
-| -------------------------- | ------------: |
-| Spacing between label and toggle |        `12px` |
+### Spacing
 
+| Property                  | Element                         | Core token            | Value                |
+| :------------------------ | :------------------------------ | :-------------------- | :------------------- |
+| `padding`                 | Thumb                           | `spacing-03`          | 0.5rem / 8px         |
+| `margin-left/right`*      | Switch                          | `spacing-03`          | 0.5rem / 8px         |
+| `padding`                 | Track                           | `spacing-04`          | 0.75rem / 12px       |
 
-
-## User Interface Design Considerations
-
-- Switch toggles should be used in place of radio buttons whenever the options are opposites of each other (i.e. yes/no, on/off, etc).
-- Try to present your lists vertically, with one choice per line.
+_*Depending of the position of the label_
 
 ## Links and references
 
-- https://xd.adobe.com/view/23e2cca4-5021-490a-a548-e99a9b4a2006-76b1/screen/c3026d48-f954-4978-91e4-05d323ee078c/variables/
+- [React CDK component](https://developer.dxc.com/tools/react/next/#/components/switch)
+- [Angular CDK component](https://developer.dxc.com/tools/angular/next/#/components/switch)
 
 ____________________________________________________________