diff --git a/.storybook/3.COLORS.stories.mdx b/.storybook/3.COLORS.stories.mdx
index 507fade1c..fce6ef662 100644
--- a/.storybook/3.COLORS.stories.mdx
+++ b/.storybook/3.COLORS.stories.mdx
@@ -1,20 +1,12 @@
import { Meta } from '@storybook/addon-docs';
-import ActionaleMessage from '../ui/components/ui/actionable-message';
import designTokenDiagramImage from './images/design.token.graphic.svg';
-
+
# Color
Color is used to express style and communicate meaning.
-
-
-
-
## Design tokens
We are importing design tokens as CSS variables from [@metamask/design-tokens](https://github.com/MetaMask/design-tokens) repo to help consolidate colors and enable theming across all MetaMask products.
diff --git a/.storybook/4.BREAKPOINTS.stories.mdx b/.storybook/4.BREAKPOINTS.stories.mdx
new file mode 100644
index 000000000..1ddd2c420
--- /dev/null
+++ b/.storybook/4.BREAKPOINTS.stories.mdx
@@ -0,0 +1,125 @@
+import { Meta } from '@storybook/addon-docs';
+
+
+
+# Breakpoints
+
+Breakpoints are used for responsive layout
+
+## Screen Sizes
+
+There are 4 screen sizes that make up the breakpoints for the MetaMask extension
+
+- base: `0px`
+- sm: `576px`
+- md: `768px`
+- lg: `1280px`
+
+### SCSS
+
+There are Sass variables and mixins available for use for both min and max screens sizes
+
+### Variables
+
+```css
+$screen-sm-max /* 575px */
+$screen-md-max /* 767px */
+$screen-lg-max /* 1279px */
+
+$screen-sm-min /* 576px */
+$screen-md-min /* 768px */
+$screen-lg-min /* 1280px */
+```
+
+### Mixins
+
+```css
+/* Max screen size */
+@include screen-sm-max {
+ /* equivalent css @media screen and (max-width: 575px) */
+}
+@include screen-md-max {
+ /* equivalent css @media screen and (max-width: 767px) */
+}
+@include screen-lg-max {
+ /* equivalent css @media screen and (max-width: 1279px) */
+}
+
+/* Min screen size */
+@include screen-sm-min {
+ /* equivalent css @media screen and (min-width: 576px) */
+}
+@include screen-md-min {
+ /* equivalent css @media screen and (min-width: 768px) */
+}
+@include screen-lg-min {
+ /* equivalent css @media screen and (min-width: 1280px) */
+}
+```
+
+Migrating from the old sass variables to the new mixins looks like this
+
+```css
+/* Max width */
+/* Instead of the media query and sass variable */
+@media screen and (max-width: $break-small) {
+ right: 16px;
+}
+
+/* Use the sass mixin */
+@include screen-sm-max {
+ right: 16px;
+}
+
+/* Min width */
+/* Instead of the media query and sass variable */
+@media screen and (min-width: $break-large) {
+ left: 16px;
+}
+
+/* Use the sass mixin */
+@include screen-sm-min {
+ left: 16px;
+}
+```
+
+## Takeaways
+
+- Try to avoid using static media queries in your code.
+- Try to use the provided SCSS mixins
+
+### ❌ Don't do this
+
+Don't use static media queries in your code.
+
+```css
+/**
+* Don't do this
+* Static media queries create inconsistency and could break the UI if we want to update them in future
+**/
+.account-menu {
+ @media screen and (min-width: 769px) {
+ right: calc((100vw - 80vw) / 2);
+ }
+
+ @media screen and (min-width: 1281px) {
+ right: calc((100vw - 65vw) / 2);
+ }
+}
+```
+
+### ✅ Do this
+
+Do use the provided Sass mixins
+
+```css
+.account-menu {
+ @include screen-md-min {
+ right: calc((100vw - 80vw) / 2);
+ }
+
+ @include screen-lg-min {
+ right: calc((100vw - 65vw) / 2);
+ }
+}
+```
diff --git a/.storybook/preview.js b/.storybook/preview.js
index 517e7820a..2e7bc26bc 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -30,7 +30,7 @@ addParameters({
storySort: {
order: [
'Getting Started',
- 'Design Tokens',
+ 'Foundations',
'Components',
['UI', 'App'],
'Pages',
diff --git a/ui/css/design-system/breakpoints.scss b/ui/css/design-system/breakpoints.scss
index 80a4176b0..61e1f3c03 100644
--- a/ui/css/design-system/breakpoints.scss
+++ b/ui/css/design-system/breakpoints.scss
@@ -1,5 +1,66 @@
+@use "sass:map";
+
/*
-Responsive Breakpoints
+Responsive breakpoints
+*/
+
+// Screen sizes
+$screen-sizes-map: (
+ 'sm': 576px,
+ 'md': 768px,
+ 'lg': 1280px,
+);
+
+// Max width screen size
+$screen-sm-max: calc(#{map.get($screen-sizes-map, "sm")} - 1px);
+$screen-md-max: calc(#{map.get($screen-sizes-map, "md")} - 1px);
+$screen-lg-max: calc(#{map.get($screen-sizes-map, "lg")} - 1px);
+
+// Min width screen size
+$screen-sm-min: map.get($screen-sizes-map, "sm");
+$screen-md-min: map.get($screen-sizes-map, "md");
+$screen-lg-min: map.get($screen-sizes-map, "lg");
+
+// Max width media query mixins
+@mixin screen-sm-max {
+ @media screen and (max-width: $screen-sm-max) {
+ @content;
+ };
+}
+
+@mixin screen-md-max {
+ @media screen and (max-width: $screen-md-max) {
+ @content;
+ };
+}
+
+@mixin screen-lg-max {
+ @media screen and (max-width: $screen-lg-max) {
+ @content;
+ };
+}
+
+// Min width media query mixins
+@mixin screen-sm-min {
+ @media screen and (min-width: $screen-sm-min) {
+ @content;
+ };
+}
+
+@mixin screen-md-min {
+ @media screen and (min-width: $screen-md-min) {
+ @content;
+ };
+}
+
+@mixin screen-lg-min {
+ @media screen and (min-width: $screen-lg-min) {
+ @content;
+ };
+}
+
+/*
+DEPRECATED
*/
$break-small: 575px;
$break-midpoint: 780px;