Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add elevation enums + docs

Browse source
This commit is contained in:
Nate Butler 2023-10-23 13:50:39 -04:00
parent 297cef14ed
commit c1c9db2ae2
3 changed files with 154 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

85
crates/ui2/src/elevation.md Normal file
View file

@ -0,0 +1,85 @@
TODO: Originally sourced from Material Design 3, Rewrite to be more Zed specific
# Elevation
Zed applies elevation to all surfaces and components, which are categorized into levels.
Elevation accomplishes the following:
- Allows surfaces to move in front of or behind others, such as content scrolling beneath app top bars.
- Reflects spatial relationships, for instance, how a floating action button’s shadow intimates its disconnection from a collection of cards.
- Directs attention to structures at the highest elevation, like a temporary dialog arising in front of other surfaces.
Elevations are the initial elevation values assigned to components by default.
Components may transition to a higher elevation in some cases, like user interations.
On such occasions, components transition to predetermined dynamic elevation offsets. These are the typical elevations to which components move when they are not at rest.
## Understanding Elevation
Elevation can be thought of as the physical closeness of an element to the user. Elements with lower elevations are physically further away from the user on the z-axis and appear to be underneath elements with higher elevations.
Material Design 3 has a some great visualizations of elevation that may be helpful to understanding the mental modal of elevation. [Material Design – Elevation](https://m3.material.io/styles/elevation/overview)
## Elevation
1. App Background (e.x.: Workspace, system window)
1. UI Surface (e.x.: Title Bar, Panel, Tab Bar)
1. Elevated Surface (e.x.: Palette, Notification, Floating Window)
1. Wash
1. Modal Surfaces (e.x.: Modal)
1. Dragged Element (This is a special case, see Layer section below)
### App Background
The app background constitutes the lowest elevation layer, appearing behind all other surfaces and components. It is predominantly used for the background color of the app.
### UI Surface
The UI Surface, located above the app background, is the standard level for all elements
Example Elements: Title Bar, Panel, Tab Bar, Editor
### Elevated Surface
Non-Modal Elevated Surfaces appear above the UI surface layer and is used for things that should appear above most UI elements like an editor or panel, but not elements like popovers, context menus, modals, etc.
Examples: Notifications, Palettes, Detached/Floating Windows, Detached/Floating Panels
You could imagine a variant of the assistant that floats in a window above the editor on this elevation, or a floating terminal window that becomes less opaque when not focused.
### Wash
Wash denotes a distinct elevation reserved to isolate app UI layers from high elevation components such as modals, notifications, and overlaid panels. The wash may not consistently be visible when these components are active. This layer is often referred to as a scrim or overlay and the background color of the wash is typically deployed in its design.
### Modal Surfaces
Modal Surfaces are used for elements that should appear above all other UI elements and are located above the wash layer. This is the maximum elevation at which UI elements can be rendered
Elements rendered at this layer have an enforced behavior: Any interaction outside of the modal will either dismiss the modal or prompt an action (Save your progress, etc) then dismiss the modal.
If the element does not have this behavior, it should be rendered at the Elevated Surface layer.
## Layer
Each elevation that can contain elements has its own set of layers that are nested within the elevations.
1. TBD (Z -1 layer)
1. Element (Text, button, surface, etc)
1. Elevated Element (Popover, Context Menu, Tooltip)
999. Dragged Element -> Highest Elevation
Dragged elements jump to the highest elevation the app can render. An active drag should _always_ be the most foreground element in the app at any time.
🚧 Work in Progress 🚧
## Element
Each elevation that can contain elements has it's own set of layers:
1. Effects
1. Background
1. Tint
1. Highlight
1. Content
1. Overlay
🚧 Work in Progress 🚧

129
crates/ui2/src/elevation.rs
View file

@ -1,63 +1,70 @@
// TODO: Originally source from Material Design 3
// TODO: Rewrite to be more Zed specific
#[doc = include_str!("elevation.md")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Elevation {
ElevationIndex(ElevationIndex),
LayerIndex(LayerIndex),
ElementIndex(ElementIndex),
}
//! # Elevation
//!
//! Elevation in Zed applies to all surfaces and components. Elevation is categorized into levels.
//!
//! Elevation accomplishes the following:
//! - Allows surfaces to move in front of or behind others, such as content scrolling beneath app top bars.
//! - Reflects spatial relationships, for instance, how a floating action button’s shadow intimates its disconnection from a collection of cards.
//! - Directs attention to structures at the highest elevation, like a temporary dialog arising in front of other surfaces.
//!
//! Elevations are the initial elevation values assigned to components by default.
//!
//! Components may transition to a higher elevation in some cases, like user interations.
//!
//! On such occasions, components transition to predetermined dynamic elevation offsets. These are the typical elevations to which components move when they are not at rest.
//!
//! ## Understanding Elevation
//!
//! Elevation can be thought of as the physical closeness of an element to the user. Elements with lower elevations are physically further away from the user on the z-axis and appear to be underneath elements with higher elevations.
//!
//! Material Design 3 has a some great visualizations of elevation that may be helpful to understanding the mental modal of elevation. [Material Design – Elevation](https://m3.material.io/styles/elevation/overview)
//!
//! ## Elevation Level Overview
//!
//! Zed integrates six unique elevation levels in its design system. The elevation of a surface is expressed as a whole number ranging from 0 to 5, both numbers inclusive. A component’s elevation is ascertained by combining the component’s resting elevation with any dynamic elevation offsets.
//!
//! The levels are detailed as follows:
//!
//! 0. App Background (e.x.: Workspace, system window)
//! 1. UI Surface (e.x.: Title Bar, Panel, Tab Bar)
//! 2. Non-Modal Elevated Surfaces (e.x.: Floating Window)
//! 3. Elevated Elements (e.x.: Popover, Context Menu, Tooltip)
//! 4. Wash
//! 5. Modal Elevated Surfaces (e.x.: Palette, Modal, Notification)
//! 6. Dragged Element
//!
//! ## 0. App Background
//!
//! The app background constitutes the lowest elevation layer, appearing behind all other surfaces and components. It is predominantly used for the background color of the app.
//!
//! ## 1. UI Surface
//!
//! The UI Surface is the standard elevation for all elements and is placed above the app background.
//!
//! ## 2. Elevated Elements
//!
//! Elevated elements appear above the UI surface layer surfaces and components. Elevated elements are predominantly used for creating popovers, context menus, and tooltips.
//!
//! ## 3. Wash
//!
//! Wash denotes a distinct elevation reserved to isolate app UI layers from high elevation components such as modals, notifications, and overlaid panels. The wash may not consistently be visible when these components are active. This layer is often referred to as a scrim or overlay and the background color of the wash is typically deployed in its design.
//!
//! ## 4. Focused Element
//!
//! Focused elements obtain a higher elevation above surfaces and components at wash elevation. They are often used for modals, notifications, and overlaid panels and indicate that they are the sole element the user is interacting with at the moment.
//!
//! ## 5. Dragged Element
//!
//! Dragged elements gain the highest elevation, thus appearing above surfaces and components at the elevation of focused elements. These are typically used for elements that are being dragged, following the cursor
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ElevationIndex {
AppBackground,
UISurface,
ElevatedSurface,
Wash,
ModalSurfaces,
DraggedElement,
}
pub enum Elevation {}
impl ElevationIndex {
pub fn usize(&self) -> usize {
match *self {
ElevationIndex::AppBackground => 0,
ElevationIndex::UISurface => 100,
ElevationIndex::ElevatedSurface => 200,
ElevationIndex::Wash => 300,
ElevationIndex::ModalSurfaces => 400,
ElevationIndex::DraggedElement => 900,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LayerIndex {
BehindElement,
Element,
ElevatedElement,
}
impl LayerIndex {
pub fn usize(&self) -> usize {
match *self {
LayerIndex::BehindElement => 0,
LayerIndex::Element => 100,
LayerIndex::ElevatedElement => 200,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ElementIndex {
Effect,
Background,
Tint,
Highlight,
Content,
Overlay,
}
impl ElementIndex {
pub fn usize(&self) -> usize {
match *self {
ElementIndex::Effect => 0,
ElementIndex::Background => 100,
ElementIndex::Tint => 200,
ElementIndex::Highlight => 300,
ElementIndex::Content => 400,
ElementIndex::Overlay => 500,
}
}
}

1
crates/ui2/src/prelude.rs
View file

@ -4,6 +4,7 @@ pub use gpui2::{
};
pub use crate::color::*;
pub use crate::elevation::*;
use crate::settings::user_settings;
pub use crate::{theme, ButtonVariant, ElementExt, Theme};