diff --git a/packages/docs/pages/foundations/elevation/best-practices.mdx b/packages/docs/pages/foundations/elevation/best-practices.mdx new file mode 100644 index 0000000000..ae16ceb49f --- /dev/null +++ b/packages/docs/pages/foundations/elevation/best-practices.mdx @@ -0,0 +1,49 @@ +# Best Practices + +Elevation tokens are divided in three types: + +- Focus Ring – Identified by the prefix `$focus-ring` followed by a suffix that indicates the the semantic value according to the colors guidelines (`base`, `accent`, or `critical`). +- Shadow – Identified by the prefix `$shadow` followed by suffixes that are numbers that are agnostic to the token value, they just represent a crescent order. +- Z-index – Identified by the prefix `$z` followed by suffixes that are numbers that are agnostic to the token value, they just represent a crescent order. + +## Focus Ring + +Include focus states for merchants that prefer or require keyboard navigation (a web standard mentioned in the [rationale](https://shoreline.vtex.com/foundations/elevation/rationale)) and to highlight error states on form fields. + +![Focus Ring](public/assets/focus-ring.png) + +| Token | Usage | +| :------------ | :---------- | +| `$focus-ring-base` | Focus ring of form fields, actions in neutral colors (Secondary and Tertiary Buttons, and items in a Menu), and popovers | +| `$focus-ring-accent` | Focus ring of actions in accent color (Primary Buttons) | +| `$focus-ring-critical` | Focus ring of form fields in error state and actions in critical colors (Critical Buttons and critical items in a Menu) | + +## Shadow + +As mentioned in the [rationale](https://shoreline.vtex.com/foundations/elevation/rationale), use shadows to indicate that an element is over another and there is content hidden below it. + +![Shadow](public/assets/shadow.png) + +| Token | Usage | +| :------------ | :---------- | +| `$shadow-1` | Popovers | +| `$shadow-2` | Modal, Drawer, and Toast | + +## Z-index + +Z-index is the CSS property that controls the stacking order of elements on a page, measured along the z-axis. A higher z-index value means that an element will appear in front of another with a lower z-index value. Elements in the Admin are stacked as described below. + +![Z-index](public/assets/z-index.png) + +| Token | Usage | +| :------------ | :---------- | +| `$z-1` | Page Content, Page Header | +| `$z-2` | Drawer Backdrop | +| `$z-3` | Drawer | +| `$z-4` | Modal Backdrop | +| `$z-5` | Modal | +| `$z-6` | Popover | +| `$z-7` | Toast | +| `$z-8` | *No scenarios mapped* | +| `$z-9` | Tooltip | +| `$z-10` | Floating contextual help | diff --git a/packages/docs/public/assets/focus-ring.png b/packages/docs/public/assets/focus-ring.png new file mode 100644 index 0000000000..3b98d237fb Binary files /dev/null and b/packages/docs/public/assets/focus-ring.png differ diff --git a/packages/docs/public/assets/shadow.png b/packages/docs/public/assets/shadow.png new file mode 100644 index 0000000000..69463aa238 Binary files /dev/null and b/packages/docs/public/assets/shadow.png differ diff --git a/packages/docs/public/assets/z-index.png b/packages/docs/public/assets/z-index.png new file mode 100644 index 0000000000..187ef7638f Binary files /dev/null and b/packages/docs/public/assets/z-index.png differ