Add drawer component documentation
Usage
Dos and dont's
|
|
---|---|
Use to display additional or supplemental information to the user about an element or item. | Use for critical interactions, such as confirming a deletion event. |
Use for complex creation, edit, or management experiences. | Use when to display large tables, data sets or metrics that are better suited to a larger view. |
Trigger the drawer after a user has taken action on an item. | Surprise the user by opening a drawer unexpectedly. |
Include one focusable element within the drawer. | Close the drawer unless the user has taken action to do so. |
Layout content based on the pajamas layout and spacing guidelines. | |
Use an icon as the primary trigger when an element or item's main action is different than opening a drawer. | |
Include a descriptive hover state when using an icon to trigger drawer interaction. |
Example use cases:
- Show more information about an issue without taking the user to a new page
- Show more information about a feature without taking the user to the documentation
- Show more information about a vulnerability instead of using a modal
Other possible uses cases:
- Changing the setting of a feature
- Changing the configuration of a feature
- Adding / Removing / Adjusting permissions of a member
- Setting a users status
- Editing an issue's information
- Editing an epic's information
Sections:
There are two main sections of a drawer.
- Header
- Content
Header:
- The title is set in
ui/02/h2-4base
with 24px spacing above and below. - Actions are left-aligned and below the title.
- The close icon is always present and right-aligned in the header.
- The title should truncate after 3 lines to avoid pushing content too far down in the drawer.
Content:
Content selection should be based on the experience you intend to promote. Content should be structured according to our layout and content guidelines.
Placement:
By default, drawers should be pinned to the top-right and bottom the window directly below the global navigation. Drawers should extend the entire height of the browser, much like the issue sidebar does toady.
Interaction:
The drawer will appear following the motion guidelines
-
200ms with an ease-in animation.
-
By default, everything is overflowed by the drawer unless you designate a component not to be.
-
IF full-width elements exist, define their behavior as required by the experience you are designing.
Open/Close:
Opening:
-
Like modals, drawers should never take the user by surprise when they open. Don’t surprise users by opening a drawer. Let a user’s action, such as using a button, following a link or selecting an option, trigger the drawer.
-
By default, items that require a drawer should use the icon.
-
When there are multiple actions associated with an item, use the icon paired with an actions dropdown. The action dropdown should contain an option to open the drawer. This action can be called "More information" or another appropriate title depending on the experience you are intending to create.
Closing:
-
There is one primary way to close the modal, by using the close button/icon in the actions section. All drawers should have this action available to users.
-
The second way to close the modal is by using the
esc
key. This is mainly to help with accessibility.
Scrolling:
The drawer is designed to allow for scrolling content. When scrolling begins, the drawer content scrolls below the header.
States:
Loading:
The drawer should utilize the skeleton loading pattern when possible.
Empty:
I an empty state is required, please follow the empty-state guidelines while being mindful of illustration size.
Small screens and mobile:
The drawer maintains the same behavior all the way down to the small breakpoint, at which point it begins taking up 100% of the viewport width.
Accessibility:
- Drawer states (expanded/collapsed) should be announced by a screen reader (SR).
- Focus moves within the drawer when expanded.
- Intentional keyboard trap keeps tab order (looped) within the drawer until it is collapsed. This is so a user cannot focus on anything hidden under the drawer.
-
esc
key should collapse the drawer along with the close button.
Design specifications
Color, spacing, dimension, and layout specific information pertaining to this component can be viewed using the following link:
Sketch Measure Preview for drawers