Merge pull request #574 from dxc-technology/draft-3.7.0-upload

Merge draft-3.7.0-upload in component-upload branch

Author: aweell

contributing/assets/components/upload_images.xd

@@ -4,44 +4,162 @@ The upload component is used to choose files from any location in the local mach
 
 ## Usage
 
-- Use the specific mode based on the application requirements
-- Add some explanation text in the case that it is needed to clarify the information to the user
-- By default, the drag and drop appearance is handled by the browser, in case it wants to be customized is the responsibility of the developer
-- If the upload process fails, please show an error message avoiding technical or undetermined information (i.e '0x94 ERROR_PATH_BUSY') that won't be understood by the user of the application
+### Do's
 
+* Provide a meaninful label and helper text in order to help the user understand the files expected
+* When displaying errors, provide feedback about the type of error using the error message
+* When the upload process fails, provide useful information instead of showing an error message using technical or undetermined information (i.e '0x94 ERROR_PATH_BUSY')
 
+### Don'ts
+
+* Use the upload component to upload multiple files inside a modal dialog
+* Use a variant with drag and drop functionality when designing for mobile devices
+
+
+## Variants
+
+![Upload component variants](images/upload_variants.png)
+
+_Upload component variants_
+
+|  Name        | Use case                                                                             |
+| :----------- | :----------------------------------------------------------------------------------- |
+| **File**     | Use the file variant when designing for multidevice                                  |
+| **Filedrop** | Use in large or complex forms when designing only for desktop                        |
+| **Dropzone** | Choose the dropzone when the main purpose of the content is to upload files/images   |
 
 ## States
 
-### Default
+The component upload is made-up of an input (type: file) and a file-item(s).
+
+### File
+
+The element has the following states: **Enabled**, **hover**, **focus**, **active** and **disabled**.
+
+![File variant upload states](images/upload_file_states.png)
+
+_File variant upload states_
+
+### Filedrop
+
+The element has the following states: **Enabled**, **hover**, **focus**, **active**, **dragover** and **disabled**.
+
+![Filedrop variant upload states](images/upload_filedrop_states.png)
+
+_Filedrop variant upload states_
+
+### Dropzone
+
+The element has the following states: **Enabled**, **hover**, **focus**, **active**, **dragover** and **disabled**.
+
+![Dropzone variant upload states](images/upload_dropzone_states.png)
+
+_Dropzone variant upload states_
+### File items
+
+The element has the following states: **Enabled**, **hover/focus**, **active**, **loading** and **error**.
+
+![File item states](images/upload_states_fileitem.png)
+
+_File item states_
+
+## Anatomy
+
+![Component upload anatomy](images/upload_anatomy.png)
+
+1. Label
+2. Drag and drop area
+3. Error message
+4. Error indicator
+5. Action - Remove file
+6. Helper text
+7. Upload button
+8. File preview
+9. File name
+10. Loading indicator
+11. File item container
+
+## File item with preview
+
+When the files to upload are mainly images, the preview can provide more feedback to the user rather than the name of the file, preventing errors loading content.
+
+![File item with preview example](images/upload_fileitem_preview.png)
+
+_File item with preview example_
+
+## Loading content
+
+When handling with large file sizes the file item should provide feedback to the user about the loading state. While the file is being loaded, the action to remove the file can not be performed.
+
+![Loading content example](images/upload_loading.png)
+
+_Loading content state_
 
-![Upload with the default preview of the component](images/upload_default.png)
+## Design Specifications
 
-_Upload with the default preview of the component_
+![Upload design specifications](images/upload_specs.png)
 
-### Drag and drop
+_Upload design specifications_
 
-![Upload with drag and drop action of a file](images/upload_dragover.png)
+### Color
 
-_Upload with drag and drop action of a file_
+#### Base
 
-### Hover state
+| Component token               | Element                     | Core token                  | Value         |
+| :---------------------------- | :-------------------------- | :-------------------------- | :------------ |
+| `dropBorderColor`             | Drag and drop area          | `color-black`               |   #000000     |
+| `fileItemBorderColor`         | File item                   | `color-grey-300`            |   #cccccc     |
+| `fileItemIconColor`           | File item                   | `color-black`               |   #000000     |
+| `labelFontColor`              | Label                       | `color-black`               |   #000000     |
+| `helperTextFontColor`         | Helper text                 | `color-black`               |   #000000     |
+| `dropLabelFontColor`          | Drop label                  | `color-black`               |   #000000     |
 
-![Example of an item hovered](images/upload_preview.png)
 
-_Example of an item hovered_
+#### Interactive
 
-### Success and error
+| Component token                         | Element                     | Core token                  | Value         |
+| :-------------------------------------- | :-------------------------- | :-------------------------- | :------------ |
+| `disabledLabelFontColor`                | Label:disabled              | `color-grey-500`            |   #999999     |
+| `disabledHelperTextFontColor`           | Helper text:disabled        | `color-grey-500`            |   #999999     |
+| `disabledDropLabelFontColor`            | Drop label:disabled         | `color-grey-500`            |   #999999     |
+| `focusDropBorderColor`                  | Dnd border:focus            | `color-blue-600`            |   #0095ff     |
+| `disabledDropBorderColor`               | Dnd border:disabled         | `color-grey-500`            |   #999999     |
+| `focusDropBackgroundColor`              | Dnd fill:focus              | `color-blue-50`             |   #f5fbff     |
+| `hoverFileItemIconBackgroundColor`      | File item icon:hover        | `color-grey-100`            |   #f2f2f2     |
+| `activeFileItemIconBackgroundColor`     | File item icon:active       | `color-grey-300`            |   #cccccc     |
+| `errorFileItemBorderColor`              | File item:error             | `color-red-700`             |   #d0011b     |
+| `errorFileItemBackgroundColor`          | File item:error             | `color-red-200`             |   #ffccd3     |
+| `errorMessageFontColor`                 | File item:error             | `color-red-700`             |   #d0011b     |
 
-Provide feedback to the users regarding the issues their files may face, or indicate that the files upload was succesfull. An alert type `success` or `error` should be placed on the top right corner of the upload container.
 
-![Component success feedback](images/upload_success.png)
+### Typography
 
-_Component success feedback_
+| Property        | Element        | Token                   | Value           |
+| :-------------- | :------------- | :---------------------- | :-------------- |
+| `font-family`   | Label          | `font-family-sans`      | Open Sans       |
+| `font-size`     | Label          | `font-scale-02`         | 0.875rem / 14px |
+| `font-weight`   | Label          | `font-bold`             | 600             |
+| `line-height`   | Label          | `font-leading-loose-01` | 1.75em          |
+| `font-family`   | Helper text    | `font-family-sans`      | Open Sans       |
+| `font-size`     | Helper text    | `font-scale-01`         | 12px            |
+| `font-weight`   | Helper text    | `font-regular`          | 400             |
+| `line-height`   | Helper text    | `font-leading-normal`   | 1.5em           |
+| `font-family`   | Drop label     | `font-family-sans`      | Open Sans       |
+| `font-size`     | Drop label     | `font-scale-03`         | 1rem / 16px     |
+| `font-weight`   | Drop label     | `font-regular`          | 400             |
+| `font-family`   | Error message  | `font-family-sans`      | Open Sans       |
+| `font-size`     | Error message  | `font-scale-01`         | 0.75rem / 12px  |
+| `font-weight`   | Error message  | `font-regular`          | 400             |
+| `line-height`   | Error message  | `font-leading-normal`   | 1.5em           |
 
-![Component error feedback](images/upload_error.png)
+### Border
 
-_Component error feedback_
+| Property        | Element               | Token             | Value           |
+| :-------------- | :-------------------- | :---------------- | :-------------- |
+| `border`        | Drag and drop area    | `-`               | dashed 2px      |
+| `border-radius` | Drag and drop area    | `-`               | 4px             |
+| `border`        | File item             | `-`               | solid 1px       |
+| `border-radius` | File item             | `-`               | 4px             |
 
 
 ## Links and references