UI layers documentation
Proposal
Based on gitlab-org&2027, create documentation that addresses different aspects of UI layering. A new “Layers” section should be created under the Layout section of Pajamas.
Examples behaviors and attributes:
- Sticky/fixed
- Scrolling
- Overlay
- Shadows
- Borders
Documentation should address:
- Dimensional hierarchy and content relationships—not just top-down, or scale, but also depth (think
z-index
), and dynamic changes based on state or overflow. - Visual styles and affordance that indicate depth, content boundaries, and state.
- Accessibility considerations for UI layers.
Shadow definitions:
sm shadow | md shadow | lg shadow | xl shadow |
---|
Instances:
Stacking & overflow layers | Interactive layers |
---|
Shadow definition
sm-shadow | md-shodow | lg shadow | xl shadow |
---|---|---|---|
sm shadow
Use cases:
- Surfaces that require a shadow boundary.
- Surfaces that can be moved or dragged by the user.
Components:
- Card (static, not being interacted with)
- Other components that require a boundary
Examples:
Issues cards in an issue board.
Specs:
box-shadow:
0px 2px 4px rgba(0, 0, 0, 0.08),
0px 0px 1px rgba(0, 0, 0, 0.24);
md shadow
Use cases:
- Surfaces that stack or overlay above existing surfaces with an elevation. see stacking & overflow layers
- Small to medium components that appear on_hover or on_click.
- Surfaces that have content that scrolls beneath a layer. see stacking & overflow layers
Components:
- Popover
- Flyout menu
- Stacked/layered components.
Examples:
Popover - md shadow |
---|
Specs:
box-shadow:
0px 0px 2px rgba(0, 0, 0, 0.16),
0px 2px 8px rgba(0, 0, 0, 0.16);
lg shadow
Use cases:
- Small to medium components that appear and have motion.
- Components being dragged/moved in the UI. see interactive layers
Components:
- Error alerts
- Toasts
- Card on_move or drag by the user.
Examples:
error alert - lg shadow |
---|
Specs:
box-shadow:
0px 0px 4px rgba(0, 0, 0, 0.16),
0px 4px 12px rgba(0, 0, 0, 0.16);
xl shadow
Use cases:
- Large surfaces with elevation in the UI.
Components:
- Modal
- Drawer
Examples:
modal - xl shadow |
---|
Specs:
box-shadow:
0px 0px 2px rgba(0, 0, 0, 0.24),
0px 4px 16px rgba(0, 0, 0, 0.24);
Stacking & overflow layers
Definition:
Layers that need to appear above a layer with an existing elevation should follow the stacking guidelines. By default, these stacked layers will use the md-shadow.
Use case:
- Content scrolls beneath static elements
...
Example:
Interactive layers
Definition:
Layers that can be moved or dragged by the user use the lg shadow to create a greater sense of depth in the UI and define the element from other elements that may have an existing elevation.
Detail:
/cc @tauriedavis