diff --git a/src/pages/components/file-uploader/images/dropdown-usage-10b.png b/src/pages/components/file-uploader/images/dropdown-usage-10b.png
new file mode 100644
index 00000000000..5dde715cb70
Binary files /dev/null and b/src/pages/components/file-uploader/images/dropdown-usage-10b.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-1.png b/src/pages/components/file-uploader/images/file-uploader-usage-1.png
index 925c65131f8..96ae5a47150 100644
Binary files a/src/pages/components/file-uploader/images/file-uploader-usage-1.png and b/src/pages/components/file-uploader/images/file-uploader-usage-1.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-10a.png b/src/pages/components/file-uploader/images/file-uploader-usage-10a.png
new file mode 100644
index 00000000000..06256da9f44
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-10a.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-10b.png b/src/pages/components/file-uploader/images/file-uploader-usage-10b.png
new file mode 100644
index 00000000000..5dde715cb70
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-10b.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-2.png b/src/pages/components/file-uploader/images/file-uploader-usage-2.png
index 90d02755cd6..023662b8238 100644
Binary files a/src/pages/components/file-uploader/images/file-uploader-usage-2.png and b/src/pages/components/file-uploader/images/file-uploader-usage-2.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-3.png b/src/pages/components/file-uploader/images/file-uploader-usage-3.png
index 3f5a842b538..341a2b42e7f 100644
Binary files a/src/pages/components/file-uploader/images/file-uploader-usage-3.png and b/src/pages/components/file-uploader/images/file-uploader-usage-3.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-4.png b/src/pages/components/file-uploader/images/file-uploader-usage-4.png
new file mode 100644
index 00000000000..dade30c7fc3
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-4.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-5.png b/src/pages/components/file-uploader/images/file-uploader-usage-5.png
new file mode 100644
index 00000000000..bf25a306acf
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-5.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-6.png b/src/pages/components/file-uploader/images/file-uploader-usage-6.png
new file mode 100644
index 00000000000..d58cb9ec1c3
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-6.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-7a.png b/src/pages/components/file-uploader/images/file-uploader-usage-7a.png
new file mode 100644
index 00000000000..fbde3054759
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-7a.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-7b.png b/src/pages/components/file-uploader/images/file-uploader-usage-7b.png
new file mode 100644
index 00000000000..4fc9681d29c
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-7b.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-8.png b/src/pages/components/file-uploader/images/file-uploader-usage-8.png
new file mode 100644
index 00000000000..158a5511dc4
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-8.png differ
diff --git a/src/pages/components/file-uploader/images/file-uploader-usage-9.png b/src/pages/components/file-uploader/images/file-uploader-usage-9.png
new file mode 100644
index 00000000000..024c673864d
Binary files /dev/null and b/src/pages/components/file-uploader/images/file-uploader-usage-9.png differ
diff --git a/src/pages/components/file-uploader/usage.mdx b/src/pages/components/file-uploader/usage.mdx
index f54802da085..77562dcd46a 100755
--- a/src/pages/components/file-uploader/usage.mdx
+++ b/src/pages/components/file-uploader/usage.mdx
@@ -1,14 +1,15 @@
---
title: File uploader
description:
- File uploaders allow a user to transfer a file or submit content of their own.
+ File uploaders allow users to select one or more files to upload to a specific
+ location.
tabs: ['Usage', 'Style', 'Code', 'Accessibility']
---
-The file uploader allows a user to transfer a file or submit content of their
-own.
+File uploaders allow users to select one or more files to upload to a specific
+location.
@@ -16,32 +17,35 @@ own.
Overview
Live demo
-Interactions
-Upload state
-Removing files
+Formatting
+Content
+Universal behaviors
+File uploader
+Drag and drop file uploader
+References
Feedback
## Overview
-File uploader allows the user to transfer a file or submit content of their own.
+File uploaders allow users to upload content of their own. A file uploader is
+commonly found in forms, but can also live as a standalone element. There are
+two types of file uploaders—our default file uploader and a drag and drop file
+uploader.
-- A file uploader is commonly found in forms, but they can also live as stand
- alone elements.
-- **Add files** is the default text that appears with the file uploader.
-- A file uploader should always be accompanied by **Submit** or **Upload**,
- which is to be styled as a [Primary Button](/components/button/usage).
-- Use an ellipsis (...) if the filename extends beyond the width of its parent
- element.
+### Types
-
-
+| Type | Way it works |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [File uploader](#file-uploader) | Upload one or more files by clicking an action button that prompts a file selection dialog. |
+| [Drag and drop file uploader](#drag-and-drop-file-uploader) | Drag and drop selected files directly into a drop zone area to upload. |
-
+### When to use
-
-
+- Uploading one or more files.
+- Uploading files by dragging and dropping.
+- Showing the process of uploading.
## Live demo
@@ -138,46 +142,250 @@ File uploader allows the user to transfer a file or submit content of their own.
`}
-## Interactions
+## Formatting
+
+### Anatomy
+
+
+
+
+
+
+
+
+
+1. **Label:** Text to describe the action that needs to be taken.
+2. **Description:** Assistive text to help the user make an informed selection.
+3. **Button or drop zone:** The action to select a file to upload.
+4. **Uploaded file:** A file that has successfully been uploaded.
+
+### Sizing
+
+The button and uploaded files should be the same height. If the file uploader is
+present in a form with other inputs, use the same height for the form inputs and
+the file uploader for consistency.
+
+
+
+
+
+
+
+
+
+| File uploader size | Height (px/rem) | Use case |
+| ------------------ | --------------- | ------------------------------------------------------------------------------------------------- |
+| _Large_ | 48/3 | Choose this size when there is a lot of space to work with. |
+| _Medium_ | 40/2.5 | This is our default size and should be used whenever possible. |
+| _Small_ | 32/2 | Use when space is constricted or when placing a file uploader in a form that is long and complex. |
+
+### Alignment
+
+Right align the button or drop zone area with the uploaded files. Multiple files
+will stack vertically.
+
+
+
+
+
+
+
+
+
+### Placement
+
+When including a button as the action to upload a file, use either a primary or
+tertiary button depending on your use case. If there is already a primary button
+present on the page, use a tertiary button for the file uploader so it does not
+conflict with the primary action.
+
+
+
+
+
+
+
+
+
+## Content
+
+### Main elements
+
+#### Label
+
+- Labels inform users what needs to be uploaded.
+- Keep the label short and concise by limiting it to a single line of text.
+
+#### Description
+
+- Descriptions help communicate to the user what file size or format limitations
+ there are.
+
+#### Button or drop zone text
+
+- Button labels should be concise and describe the action that will be taken
+ upon click. "Add files" is the default text that appears with the file
+ uploader.
+- Drop zone area text should describe that you can either drag and drop a file
+ into the drop zone or click on the text to upload a file.
+
+#### Uploaded file text
+
+- The name of the file that has been uploaded.
+
+### Overflow
+
+Use an ellipsis (…) if the filename extends beyond the width of its parent
+element.
+
+
+
+
+
-1. The user may select 1 or more files to upload at a time. By default, any file
- type is accepted, but you can add parameters to validate a specific file
- type.
-2. The action of clicking **Add files** will trigger a browser-specific upload
- window.
-3. Once the user chooses files to upload, the browser-specific upload window
- closes and the files will appear below the **Add files** button.
-4. User clicks **Submit** or **Upload** to submit their data.
-5. Any errors that may occur with the file should appear as an inline error
- [Notification](/components/notification/usage).
+
+
+
+### Further guidance
+
+For further content guidance, see Carbon's
+[content guidelines](https://www.carbondesignsystem.com/guidelines/content/overview).
+
+### Loading states
+
+A file that is being uploaded has three distinct states—loading, success, and
+uploaded.
-
+
-## Upload state
+### Interactions
+
+#### Mouse
+
+Moving your mouse anywhere within the bounds of the drop zone area with an
+attached file will enable you to drop it inside of the area and begin to upload.
+
+
+
+
+
+
+
+
+
+To remove an uploaded file, click the "x” (or close) icon.
+
+
+
+
+
+
+
+
+
+#### Keyboard
+
+#### Upload button or drop zone:
+
+- The file uploader button or drop zone can be activated by pressing `Space` or
+ `Enter`.
+- The file uploader button or drop zone should have text or a label that
+ accurately describes the action that will be taken.
+- After the file selection dialog closes, focus should retain the user’s point
+ of regard and return to the element that invoked it.
+
+#### Uploaded file:
+
+- Pressing `Tab` shifts focus to the “x” icon.
+- Pressing `Space` or `Enter` while the "x" icon is in focus will delete the
+ file.
+
+#### Screen readers
+
+- VoiceOver: Users can upload a file by pressing `VO+Space` while the button or
+ drop zone area is in focus.
+- JAWS: Users can upload a file by pressing `Enter` or `Space` while the button
+ or drop zone area is in focus.
+- NVDA: Users can upload a file by pressing `Enter` or `Space` while the button
+ or drop zone area is in focus.
+
+### Validation
+
+When a specific file cannot be uploaded successfully it will show an error
+state. We have an option for a single line or multi-line error state depending
+on how descriptive the message needs to be. Error messages should provide clear
+guidance to help the user resolve the error.
+
+If the error relates to the file uploader as a whole instead of an individual
+file, you can alternatively use an inline error notification.
+
+
+
+
+
+
+
+
+
+## File uploader
+
+A file uploader traditionally uploads one or more files by clicking an action
+button that prompts a file selection dialog. Once you have selected one or more
+files from the dialog, the selected files will populate below the file uploader
+on the page. Your file may temporarily display a loading state before uploading
+has been successfully completed.
+
+
+
+
+
+
+
+
+
+## Drag and drop file uploader
+
+Drag and drop file uploaders are used to directly upload files by dragging and
+dropping them into a drop zone area. Alternatively, you can also traditionally
+open files through a file selection dialog by clicking the text link description
+inside the drop zone.
+
+The drop zone component lets users upload files by dragging and dropping the
+files into an area on a page, or activating a button.
+
+
+
+
+
+
+
+
-Developers using file uploader will be able to use JavaScript to inject a
-Loading component when selected files are actually being uploaded.
+When dragging files into the drop zone area, the drop zone border changes in
+color and thickness to indicate the area has been activated and is ready for
+files. Additionally once the cursor hits the drop zone area it changes with a
+preview of the file you are about to upload. The style of cursor change is
+rendered by the browser you use.
-
+
-## Removing files
+## References
-Developers will use JavaScript to inject a “close” button on each file that is
-selected to be uploaded. It's up to the developer to code the logic for removing
-these files individually. However, keep in mind that this kind of editing isn't
-supported natively in the browser.
+Page Laubheimer,
+[Drag–and–Drop: How to Design for Ease of Use](https://www.nngroup.com/articles/drag-drop/),
+(Nielsen Norman Group, 2020)
## Feedback