Repository: hashicorp/design-system
Pull request #2855: `HDS Docs` - Breakpoints
Author: login: majedelass
Labels: name: docs-website
description: Updates to the documentation website
Created: 2025-05-06T12:28:43Z | Merged: 2025-05-14T17:04:54Z

### :pushpin: Summary

If merged, this PR will add a new section within the Foundations section for Breakpoints.

Preview: https://hds-website-git-breakpoints-hashicorp.vercel.app/foundations/breakpoints

### :hammer_and_wrench: Detailed description

Following the work [done for the memo](https://go.hashi.co/memo/ds-013) describing what path we are taking and what comes next, this PR is to create the new section describing the different breakpoints, their application and how to design uses these standards.

### :link: External links

<!-- Issues, RFC, etc. -->
Memo: [Standardizing Breakpoints](https://go.hashi.co/memo/ds-013)
Jira ticket: [HDS-4831](https://hashicorp.atlassian.net/browse/HDS-4831)
Figma file: [Breakpoints project](https://www.figma.com/design/BYiBgV0JJxVSt3H1GaLOKR/Breakpoints-project?m=auto&t=ZmcUJgf31HEIuXbu-6)

***

:speech_balloon: Please consider using [conventional comments](https://conventionalcomments.org/) when reviewing this PR.


[HDS-4831]: https://hashicorp.atlassian.net/browse/HDS-4831?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ


Diff:
diff --git a/website/docs/components/app-header/partials/code/component-api.md b/website/docs/components/app-header/partials/code/component-api.md
index 49079bb8e98..79434f2913e 100644
--- a/website/docs/components/app-header/partials/code/component-api.md
+++ b/website/docs/components/app-header/partials/code/component-api.md
@@ -13,7 +13,7 @@
     A named block where the utility actions will be rendered. Typically, `Dropdown` or `Button` components should be added here, such as a help menu, user menu, or search button.
   </C.Property>
   <C.Property @name="breakpoint" @type="string" @default="1088px">
-    Set a custom breakpoint to control the page width at which the UI switches from displaying the mobile/small view vs. the desktop/view.
+    Set a custom breakpoint to control the page width at which the UI switches from displaying the mobile/small view vs. the desktop/large view.
   </C.Property>
   <C.Property @name="hasA11yRefocus" @type="boolean" @default="true">
     Controls whether a "navigator narrator" and a "skip link" are added to the navigation (provided by the [`ember-a11y-refocus` Ember addon](https://github.com/ember-a11y/ember-a11y-refocus)). It can be programmatically turned off by passing `false`. Warning: if it is set to false, then it will fail Bypass Blocks, [Success Criteria 2.4.1](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html). Since this component appears on every page, the application will not be considered conformant.
diff --git a/website/docs/components/app-side-nav/partials/code/component-api.md b/website/docs/components/app-side-nav/partials/code/component-api.md
index b8135a7fc6e..1dc403da56a 100644
--- a/website/docs/components/app-side-nav/partials/code/component-api.md
+++ b/website/docs/components/app-side-nav/partials/code/component-api.md
@@ -21,6 +21,9 @@ This is the full-fledged component (responsive and animated).
   <C.Property @name="isMinimized" @type="boolean" @default="false">
     Controls if the App Side Nav is rendered collapsed or expanded when initialized. This allows an application to preserve the collapsed/expanded state across sessions. After the initial render, this argument is altered based on user interactions (collapse/expand the App Side Nav or resize the window) and it is not a suitable way of controlling the App Side Nav state from outside after render (it’s an internal state).
   </C.Property>
+  <C.Property @name="breakpoint" @type="string" @default="1088px">
+    Set a custom breakpoint to control the page width at which the UI switches from displaying the mobile/small view vs. the desktop/large view.
+  </C.Property>
   <C.Property @name="onToggleMinimizedStatus" @type="function">
     Callback function invoked when the `AppSideNav` is collapsed or expanded. The function receives a boolean argument stating if the `AppSideNav` is minimized or not.
   </C.Property>
diff --git a/website/docs/components/app-side-nav/partials/code/how-to-use.md b/website/docs/components/app-side-nav/partials/code/how-to-use.md
index 2cbfea2b267..32663d29bcc 100644
--- a/website/docs/components/app-side-nav/partials/code/how-to-use.md
+++ b/website/docs/components/app-side-nav/partials/code/how-to-use.md
@@ -118,7 +118,7 @@ Below is an example (inspired by the Cloud UI navigation) of how the two kinds o
 
 <!-- ```handlebars
 {{!--
-for demo purposes we set `@isResponsive` to `false` but in your app it will probably need to be set to `true` 
+for demo purposes we set `@isResponsive` to `false` but in your app it will probably need to be set to `true`
 (or omitted to rely on defaults)
 --}}
 <div class="doc-app-sidenav-demo--cloud-ui">
@@ -175,7 +175,7 @@ When the App Side Nav is used in conjunction with portals, the nesting of naviga
 As mentioned above, the full-fledged `Hds::AppSideNav` component is “responsive” by default:
 
 - when the **viewport is `desktop`**, the sidebar navigation is static and has a fixed width
-    - the width at which the viewport is considered “desktop” is controlled by a dedicated CSS variable `--hds-app-desktop-breakpoint`; if needed it can be overwritten (at `:root` level) to define a custom “desktop” breakpoint
+    - the width at which the viewport is considered “desktop” can be overwritten using the `@breakpoint` argument
 - when the **viewport is `mobile`**, the sidebar navigation is responsive and the user can minimize or maximize its width via a toggle button (the component will take care automatically of the transitions between these two states)
     - in this case the App Side Nav occupies only a minimum width in terms of page layout, even when expanded (it partially covers the main content)
     - a toggle button is added to the App Side Nav, used to expand/minimize its width
diff --git a/website/docs/foundations/breakpoints/index.md b/website/docs/foundations/breakpoints/index.md
new file mode 100644
index 00000000000..f457c21ce99
--- /dev/null
+++ b/website/docs/foundations/breakpoints/index.md
@@ -0,0 +1,16 @@
+---
+title: Breakpoints
+caption: Standardized breakpoints for different device widths.
+description: Breakpoints are width values that standardize responsive experiences across the HashiCorp product suite.
+links:
+  figma: https://www.figma.com/design/uX4OEaJQdWfzULADchjAeN/HDS-Foundations-v2.0?node-id=13020-244&t=0N1UWbTuY6sSq3Od-1
+previewImage: assets/illustrations/foundations/breakpoints.jpg
+---
+
+<section data-tab="Guidelines">
+  @include "partials/guidelines/guidelines.md"
+</section>
+
+<section data-tab="Code">
+  @include "partials/code/how-to-use.md"
+</section>
\ No newline at end of file
diff --git a/website/docs/foundations/breakpoints/partials/code/how-to-use.md b/website/docs/foundations/breakpoints/partials/code/how-to-use.md
new file mode 100644
index 00000000000..15daf92f062
--- /dev/null
+++ b/website/docs/foundations/breakpoints/partials/code/how-to-use.md
@@ -0,0 +1,119 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography, spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which mixin is best suited to achieve the desired responsive layout. This will  depend on the design specifications, the context of the layout within the page, and how it relates with other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We also provide helpers in case you need to access the breakpoints names/values in JavaScript code.
+
+You have access to the list of breakpoint names and values using the `hdsBreakpoints` map:
+
+```javascript{data-execute=false}
+import { hdsBreakpoints } from '@hashicorp/design-system-components/utils/hds-breakpoints';
+
+// do something with a specific breakpoint value
+const myBreakpoint1 = hdsBreakpoints['xl'].value; // numeric (eg. 1440)
+const myBreakpoint2 = hdsBreakpoints['lg'].px;    // size in px (eg. 1088px)
+const myBreakpoint3 = hdsBreakpoints['sm'].rem;   // size in rem (eg. 30rem)
+
+// loop over all the breakpoints
+Object.entries(hdsBreakpoints).forEach(([name, sizes]) => {
+  // do something with a specific breakpoint value in px
+  const myBreakpointSizePx = sizes.px;
+});
+```
diff --git a/website/docs/foundations/breakpoints/partials/guidelines/guidelines.md b/website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
new file mode 100644
index 00000000000..7574c9d55c2
--- /dev/null
+++ b/website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
@@ -0,0 +1,46 @@
+Breakpoints are viewport widths where layouts adjust to support responsive experiences on varied screen sizes and devices. These values are used to create utilities and helper components that standardize changes in UI at these widths.
+
+## The ranges
+
+There are five HDS breakpoint values: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name. We don't anticipate designers needing to produce mockups for screen sizes below this width and from the audits conducted, Cloud UI has set a standard of 480px for the most narrow design. From a development perspective, in a mobile-first approach the range below 480px can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, a custom width value may be used to enhance the user experience.
+
+!!! insight
+
+If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size.
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Diagram depicting "large", "medium", and "small" screen sizes displaying a varying number of columns in rows of content blocks.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
+
+## Responsiveness in Helios
+
+Responsive behavior is already built into some Helios components. These components include, but are not limited to:
+* [App Side Nav](/components/app-side-nav) (width collapses below lg breakpoint)
+* [Stepper Nav](/components/stepper/nav) (layout shifts below sm breakpoint)
+* [Pagination](/components/pagination) (layout stacks below lg breakpoint)
diff --git a/website/public/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png b/website/public/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png
new file mode 100644
index 00000000000..725b90c20e6
Binary files /dev/null and b/website/public/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png differ
diff --git a/website/public/assets/foundations/breakpoints/breakpoints-table-example.png b/website/public/assets/foundations/breakpoints/breakpoints-table-example.png
new file mode 100644
index 00000000000..ec5a14156ce
Binary files /dev/null and b/website/public/assets/foundations/breakpoints/breakpoints-table-example.png differ
diff --git a/website/public/assets/illustrations/foundations/breakpoints.jpg b/website/public/assets/illustrations/foundations/breakpoints.jpg
new file mode 100644
index 00000000000..582b4520127
Binary files /dev/null and b/website/public/assets/illustrations/foundations/breakpoints.jpg differ


Reviews:
user: login: jorytindall
body: Nice first pass! There is some inconsistent language usage that I tried to catch, and I added some suggestions for expressing some of that content in more plain language. Whether these accurately express what you're trying to say, TBD! But take what you feel is relevant from them.
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T20:19:35Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T21:19:59Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T21:31:19Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T21:35:37Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T21:39:18Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T21:41:51Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T21:45:53Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T21:48:39Z
user: login: jorytindall
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T23:49:55Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T11:46:55Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T11:47:08Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:18:33Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:21:23Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:22:19Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:23:13Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:23:43Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:27:40Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T12:28:10Z
user: login: andgen404
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T16:34:03Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:19:05Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:19:59Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:20:43Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:32:29Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:34:01Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:35:43Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:58:23Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T17:58:40Z
user: login: KristinLBradley
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T18:30:07Z
user: login: shleewhite
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T19:06:05Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T19:52:31Z
user: login: dchyun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:08:21Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:21:01Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:26:13Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:30:20Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:31:53Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:38:22Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:41:52Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:48:03Z
user: login: dchyun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:55:33Z
user: login: jorytindall
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T20:56:51Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:34:36Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:36:28Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:37:24Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:38:38Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:42:02Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:44:10Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:47:34Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T21:50:12Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T22:01:49Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T22:08:02Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T22:32:41Z
user: login: KristinLBradley
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T22:33:53Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T22:40:31Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T22:40:50Z
user: login: dchyun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T13:28:06Z
user: login: dchyun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T13:37:40Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T14:25:20Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T14:34:31Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T14:39:14Z
user: login: dchyun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T15:03:30Z
user: login: LilithJames-HDS
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T15:14:25Z
user: login: shleewhite
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T15:41:47Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T16:59:06Z
user: login: LilithJames-HDS
body: Let me know what you think of the changes I suggested
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T17:15:38Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T18:26:25Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T18:27:18Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T18:29:33Z
user: login: LilithJames-HDS
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T19:16:52Z
user: login: LilithJames-HDS
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T19:17:40Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T22:10:14Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T22:17:12Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T22:18:22Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T22:19:20Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T22:20:43Z
user: login: jorytindall
body: I left a few small comments in the code section, and I more or less agree with @LilithJames-HDS 's notes as well. I think this should be good to go once those are resolved!
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T22:47:08Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T08:36:30Z
user: login: majedelass
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T12:06:53Z
user: login: LilithJames-HDS
body: Thanks for making those changes, this is looking great!
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T12:46:56Z
user: login: dchyun
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T13:56:22Z
user: login: KristinLBradley
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T15:40:01Z
user: login: shleewhite
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T17:30:50Z
user: login: jorytindall
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T18:00:02Z
user: login: KristinLBradley
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T21:16:49Z
user: login: MelSumner
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-13T21:21:19Z
user: login: MelSumner
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-13T21:23:34Z
user: login: MelSumner
body: Left a suggestion to make something less wordy but no blockers.
state: DISMISSED
author_association: COLLABORATOR
submitted_at: 2025-05-13T21:24:23Z
user: login: didoo
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T21:27:26Z
user: login: MelSumner
state: DISMISSED
author_association: COLLABORATOR
submitted_at: 2025-05-13T21:33:39Z
user: login: KristinLBradley
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T21:50:27Z
user: login: jorytindall
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T22:07:37Z
user: login: MelSumner
state: DISMISSED
author_association: COLLABORATOR
submitted_at: 2025-05-14T13:25:44Z
user: login: KristinLBradley
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T15:15:44Z
user: login: dchyun
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T16:47:31Z
user: login: shleewhite
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T16:59:36Z

Review comments:
diff_hunk: @@ -0,0 +1,15 @@
+---
+title: Breakpoints
+caption: Standardized breakpoints for different device widths.
+description: Standardized breakpoints for different device widths.
+previewImage: assets/illustrations/foundations/breakpoints.jpg
path: website/docs/foundations/breakpoints/index.md
user: login: jorytindall
body: A link to the Figma frame should also be included here.
created_at: 2025-05-08T19:31:16Z
author_association: CONTRIBUTOR
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: jorytindall
body: Assuming the code docs are still a WIP
created_at: 2025-05-08T19:31:42Z
author_association: CONTRIBUTOR
path: website/docs/foundations/breakpoints/partials/guidelines/overview.md
user: login: jorytindall
body: I know we used this pattern for other components/docs in the past, but it seems unnecessary to have a separate markdown file for this rather than just including it in the guidelines file.
created_at: 2025-05-08T19:32:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: [suggestion] I think you could combine the first two sentences, and at least how we define them breakpoints don't include height so that seems like it should be removed. I'm not aware of any scenario where the viewport height comes into play for responsive design (at least with regard to defining vertical breakpoints), which would promote removing the final sentence. Is there a reason why this is being included?

```suggestion
Breakpoints are the foundational building blocks for responsive design and define the viewport width where the page layout adjusts for varied screen sizes and devices. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
```
created_at: 2025-05-08T19:39:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: Couple of suggestions:
- Non-opinionated, but defining these as helper components (or even layout components) might be more explicit.
- This suggestion removes the duplicate use of the word "standardize" in the same sentence.
- Using "viewport" is a bit more explicit than "screen", and is the term that's used elsewhere in these docs.
- non-opinionated, I included stacking, I could go either way about using that term.

```suggestion
These values are then used to create utilities and helper components to standardize the adjustment stacking of the UI at different viewport sizes.
```
created_at: 2025-05-08T19:44:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: [suggestion] could be simplified a little bit.

```suggestion
Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
```
created_at: 2025-05-08T19:45:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: This sentence is pretty hard for me to parse, though I think I understand what you're saying. I took a stab (not perfect), but WDYT?

```suggestion
The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `small` breakpoint applies to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing, and increases the flexibility in implementation.
```
created_at: 2025-05-08T19:58:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: [suggestion] this seems a bit easier to read, what do you think?

```suggestion
The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, additional values can be added to enhance the user experience.
```
created_at: 2025-05-08T20:04:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: Should we be referring to this as breakpoints rather than ranges? I've seen both in these docs and I think using 
"breakpoint" is better for consistency.

```suggestion
If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
```
created_at: 2025-05-08T20:06:22Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: What do you mean by "UI placement" here? 

```suggestion
Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
```
created_at: 2025-05-08T20:07:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
+
+An example of this would be that a table-centered experience may not require additional UI adjustment at the `lg`, `xl`, and `xxl` breakpoints. The expectated beahvior for the table is to maintain its full width regardless of the breakpoint value, and that a design isn't required to elaborate this standard behavior.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: This uses a bit more plain language, WDYT?

```suggestion
For example, a UI featuring a table may not require adherence to each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
```
created_at: 2025-05-08T20:09:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
+
+An example of this would be that a table-centered experience may not require additional UI adjustment at the `lg`, `xl`, and `xxl` breakpoints. The expectated beahvior for the table is to maintain its full width regardless of the breakpoint value, and that a design isn't required to elaborate this standard behavior.
+
+![Wireframed table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+An example of a UI changing over varied screen sizes would be a landing page where cards are aligned and styled in an asymetric manner. As the screen size decreases, the cards not only shift, but the content within them does as well. This would be considered a complicated UI that requires more naunced designing at all breakpoints. In a scenario like this, designers would be expected to elaborate how this experience is adjusted in the `sm`, `md` and `lg` (if not more) screens.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: This uses more active language and adds some consistency for some of the terminology. This is pretty different from your original, so feel free to cherry pick things from it.

```suggestion
Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` breakpoints.
```
created_at: 2025-05-08T20:17:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: I would remove this final sentence also:
"While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths."

Also, it seems like "viewport width" should be plural. => "viewport widths"
created_at: 2025-05-08T21:19:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: I'm not sure if this absolutely sentence is necessary here. It seems somewhat redundant.

@jorytindall "adjustment stacking" sounds kind of awkward. Also, break points can be used to adjust designs/styles in various ways, not just in stacking layouts.
created_at: 2025-05-08T21:31:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: Break points can be used to change designs in various ways, not just for altering layouts explicitly. For example, it's common to shift font sizes according to views such as for headers. You could also change visual elements such as adding / removing borders, etc. or whatever.

I don't think we need to explain all these possibilities in detail but I wouldn't reference page layouts only or just specifically.
created_at: 2025-05-08T21:35:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: Maybe change "decreases in size" to "changes in size".
created_at: 2025-05-08T21:39:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
+
+An example of this would be that a table-centered experience may not require additional UI adjustment at the `lg`, `xl`, and `xxl` breakpoints. The expectated beahvior for the table is to maintain its full width regardless of the breakpoint value, and that a design isn't required to elaborate this standard behavior.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: @jorytindall I'd change the above suggestion to something more like the below. ("adherence" isn't quite the right word to use here.)

"a table may not require adherence to each breakpoint"
=>
"a table layout may not require changes for each breakpoint"
created_at: 2025-05-08T21:41:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
+
+An example of this would be that a table-centered experience may not require additional UI adjustment at the `lg`, `xl`, and `xxl` breakpoints. The expectated beahvior for the table is to maintain its full width regardless of the breakpoint value, and that a design isn't required to elaborate this standard behavior.
+
+![Wireframed table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+An example of a UI changing over varied screen sizes would be a landing page where cards are aligned and styled in an asymetric manner. As the screen size decreases, the cards not only shift, but the content within them does as well. This would be considered a complicated UI that requires more naunced designing at all breakpoints. In a scenario like this, designers would be expected to elaborate how this experience is adjusted in the `sm`, `md` and `lg` (if not more) screens.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: Btw, I think it could be helpful to speak in terms of "views" vs. "breakpoints" in some of the explanations.

Breakpoints are used to define "views". (For example, "sm", "md", "lg" ect. views as we are calling them but they could also be named "mobile", "tablet", etc. views if that helps in thinking about it.)
created_at: 2025-05-08T21:45:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1 @@
+Different defined widths that help standardize responsive experiences across the HashiCorp product suite.
path: website/docs/foundations/breakpoints/partials/guidelines/overview.md
user: login: KristinLBradley
body: I'm seeing this sentence appear at the top of the Guidelines. It doesn't seem needed though. (Seems redundant to the other nearby text)

<img width="756" alt="image" src="https://github.com/user-attachments/assets/3e904409-28bf-4dde-bc88-4c7e06d82f9a" />

created_at: 2025-05-08T21:48:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
+
+An example of this would be that a table-centered experience may not require additional UI adjustment at the `lg`, `xl`, and `xxl` breakpoints. The expectated beahvior for the table is to maintain its full width regardless of the breakpoint value, and that a design isn't required to elaborate this standard behavior.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: Yeah, that's a good suggestion, more plain language
created_at: 2025-05-08T23:49:55Z
author_association: CONTRIBUTOR
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: majedelass
body: They are, Cristiano is working on them.
created_at: 2025-05-09T11:46:55Z
author_association: CONTRIBUTOR
path: website/docs/foundations/breakpoints/partials/guidelines/overview.md
user: login: majedelass
body: I'll omit
created_at: 2025-05-09T11:47:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: I updated the language a bit to be a little more vague than just adjusting.
created_at: 2025-05-09T12:18:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: Updated a bit.
created_at: 2025-05-09T12:21:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: I tweaked it a bit, but this is better, thank you :)
created_at: 2025-05-09T12:22:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: I changed placement with elements instead.
created_at: 2025-05-09T12:23:13Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: Breakpoint is better, agreed.
created_at: 2025-05-09T12:23:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational blocks to responsive design. They are defined as the viewport widths/heights where page layouts adjust for varied screen size experiences. While both horizontal and vertical breakpoints can be used in responsive design, the standardization of these values will only be focused on the widths. 
+
+These values are then used to create utilities and components to help standardize the re-adjusting of UI at different standardized screen sizes.
+
+### The ranges
+
+There are five defined breakpoints and they are: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+When a breakpoint name is mentioned, it isn't only referencing the exact starting pixel value, instead, it is for the range of its application. This helps simplify language around what these ranges mean when designing. Implemention of these breakpoints has more flexibility and can be explored further in the Code tab.
+
+### Working with custom values
+
+The ranges provided are to create a cohesive *starting* experience. Although, in some rare circumstances a custom value may be needed to accomodate for specific use-cases that these values do not cover. For example: a team has learned that users with 2500px viewports started using a specific product, and require a nuanced approach in displaying the UI at that screen size. In cases like this, a value may be added on top of the established values to provide additional nuance to that experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established range, it is recommended that it be migrated to the nearest standard breakpoint. This way, experiences become consistent and predictable for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each of these breakpoints. Only when designs are considered complicated and/or constrained by UI placement should a designer take the time to show how they change as the viewport decreases in size. 
+
+An example of this would be that a table-centered experience may not require additional UI adjustment at the `lg`, `xl`, and `xxl` breakpoints. The expectated beahvior for the table is to maintain its full width regardless of the breakpoint value, and that a design isn't required to elaborate this standard behavior.
+
+![Wireframed table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+An example of a UI changing over varied screen sizes would be a landing page where cards are aligned and styled in an asymetric manner. As the screen size decreases, the cards not only shift, but the content within them does as well. This would be considered a complicated UI that requires more naunced designing at all breakpoints. In a scenario like this, designers would be expected to elaborate how this experience is adjusted in the `sm`, `md` and `lg` (if not more) screens.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: I adjusted to try to match what you're talking about Kristin, good suggestion.
created_at: 2025-05-09T12:27:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1 @@
+Different defined widths that help standardize responsive experiences across the HashiCorp product suite.
path: website/docs/foundations/breakpoints/partials/guidelines/overview.md
user: login: majedelass
body: Yeah I think ill just move this up to the description instead.
created_at: 2025-05-09T12:28:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational building blocks for responsive design and define the viewport widths where the page layout adjusts and/or changes for varied screen sizes and devices.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: andgen404
body: ```suggestion
Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
```
[Opinion] I don’t think “foundational building blocks” are needed; they feel vague. I’d go straight into what breakpoints do, like how they change the layout at different screen sizes.
created_at: 2025-05-09T14:46:48Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational building blocks for responsive design and define the viewport widths where the page layout adjusts and/or changes for varied screen sizes and devices.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: I agree with Andrew's suggestion here.
created_at: 2025-05-09T17:19:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational building blocks for responsive design and define the viewport widths where the page layout adjusts and/or changes for varied screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing, and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: ```suggestion
```
created_at: 2025-05-09T17:19:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational building blocks for responsive design and define the viewport widths where the page layout adjusts and/or changes for varied screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing, and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: Nit: Delete extra blank line (so that there's only one blank line vs. 2 in a row).
created_at: 2025-05-09T17:20:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational building blocks for responsive design and define the viewport widths where the page layout adjusts and/or changes for varied screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing, and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size. 
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframed table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Three varied screen sizes of large, medium and small. In large, there are four rows of cards, the first with one, the second with two, the third with three and the fourth with four. In medium, the first and third rows have one card while the second and fourth have two. The small, there is only one card in each row.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: ```suggestion
![Diagram depicting "large", "medium", and "small" screen sizes displaying a varying number of columns in rows of content blocks.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
```
created_at: 2025-05-09T17:32:29Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational building blocks for responsive design and define the viewport widths where the page layout adjusts and/or changes for varied screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing, and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size. 
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframed table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Three varied screen sizes of large, medium and small. In large, there are four rows of cards, the first with one, the second with two, the third with three and the fourth with four. In medium, the first and third rows have one card while the second and fourth have two. The small, there is only one card in each row.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: I tried to simplify the above. I don't think it's useful to go into granular detail explaining this image as it just provides a rough abstract example of different layouts according to different screen/view sizes.
created_at: 2025-05-09T17:34:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,42 @@
+## Breakpoints
+
+Breakpoints are the foundational building blocks for responsive design and define the viewport widths where the page layout adjusts and/or changes for varied screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing, and increases the flexibility in implementation.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: ```suggestion
The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
```
created_at: 2025-05-09T17:35:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size. 
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframed table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: ```suggestion
![Wireframe table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
```
created_at: 2025-05-09T17:58:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size. 
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframed table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: This was flagged by the linter as a misspelling
created_at: 2025-05-09T17:58:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,2 @@
+
+## How to use breakpoints
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: shleewhite
body: Will the code content be added to this PR? or in a separate one? If it will be a separate PR, then we should omit this file.
created_at: 2025-05-09T19:06:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: ```suggestion
| xs     | 0px          | 0 → 479                       |
| sm     | 480px        | 480 → 767                     |
```
[Question] Would it make sense to add in an "xs" name for those values less than 480? Since the names refer to a range of values, it may be odd if there's no way to refer to those values less than sm. This wouldn't have to have an impact on the code, more just a nomenclature for design to use. 
created_at: 2025-05-09T19:44:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,2 @@
+
+## How to use breakpoints
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: majedelass
body: This one, Cristiano will be adding it 
created_at: 2025-05-09T19:52:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: [Suggestion] We leave a lot of the interpretation of when to use the breakpoints up to the designers, but it could be helpful if we offer general guidance around when to use certain breakpoints. Such as something like "generally mobile / tablet designs start at the sm viewport". 

For example, our enterprise nav mobile design starts on the md viewport. It would improve the cohesiveness of a page if all elements with significant changes for mobile started to enter their "mobile" views at that point, instead of having some changing at one viewport and some changing at another. 

This is more for when there are bigger differences between desktop and mobile functionality. Like the nav going from expanded to collapsed or hypothetically content going from being in a table to cards. 
created_at: 2025-05-09T20:05:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,2 @@
+
+## How to use breakpoints
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: didoo
body: I'm on it
created_at: 2025-05-09T20:21:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: Have you looked at the PR for the code implementation? https://github.com/hashicorp/design-system/pull/2848
In that case, as a consumer, wouldn't you expect to use `xs` also in the mixins? And given that it doesn't work, wouldn't it be confusing (or probably you would think it's broken), no?
created_at: 2025-05-09T20:26:13Z
author_association: CONTRIBUTOR
path: website/public/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png
user: login: didoo
body: @majedelass consider changing the order of the browsers mock here, to reinforce the idea of "mobile first" design approach (plus, it will be in sync with the list in the text just above)
created_at: 2025-05-09T20:30:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: @majedelass a suggestion

```suggestion
!!! Insight

If a custom value already exists that is relatively close to an established breakpoint, we recommend to migrate it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.

!!!
```
created_at: 2025-05-09T20:31:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: > if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required

@majedelass well, it's **very** likely that such user will exist, the analytics already tell us this :)
Probably what we want to suggest to the designers is to consider the layout of the UI they're working on, and if they have a sense that at low viewport sizes may not work or may require reorganization of the content to fit the screen width, then they should use the different templates offered in our Figma UI Kit/Library (there's no mention of it, in the whole documentation page, probably an oversight?) to provide mocks at different viewport widths for the engineers.
created_at: 2025-05-09T20:38:22Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: What about simplifying the title to "Custom values" or "Custom breakpoints"?
created_at: 2025-05-09T20:41:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: ```suggestion
The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.

_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
```
created_at: 2025-05-09T20:48:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: Should this go in a banner?
created_at: 2025-05-09T20:54:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: +1 to "Custom breakpoints"
created_at: 2025-05-09T20:54:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: Yeah I saw the code implementation, and I don't think it makes sense to add a fake value there. This was just more a question of how would we refer to values less than 480, and adding the "xs" as a solution to that. 

I was looking at [Bootstrap](https://getbootstrap.com/docs/5.3/layout/breakpoints/#available-breakpoints), which does have an xs value that is set to 0 and basically doesn't do anything. They probably only have it so people can customize it, which isn't needed in our case. 
created_at: 2025-05-09T20:55:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: I might use "…we recommend migrating it to the nearest standard breakpoint."
created_at: 2025-05-09T20:55:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: We don't have an XS breakpoint though. The way it is being built is that they would use a SASS function that would be similar to `breakpoint-down('sm')` which would effectively be what you're describing. 
created_at: 2025-05-09T21:34:35Z
author_association: CONTRIBUTOR
path: website/public/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png
user: login: majedelass
body: This is a challenge mostly because we are a "desktop first" company, which is hard to say, but is unfortunately true. Which is why I started from large to small, which is how designers are going to have to start thinking about it moving forward.
created_at: 2025-05-09T21:36:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: How about:
```suggestion
!!! info

If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.

!!!
```
created_at: 2025-05-09T21:37:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: I like "Custom values," ill adjust!
created_at: 2025-05-09T21:38:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: We don't often link it in the docs because not everyone reading the docs has access to the templates themselves (consider folks who are external to the org). Although now mentioning it, we do have the link to the Figma foundations file at the top. I'll add it here so that they have a reference to it.
created_at: 2025-05-09T21:42:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: Adding the link.
created_at: 2025-05-09T21:44:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+### Working with custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! info
+
+If a custom value already exists that is relatively close to an established breakpoint, it is recommended that it be migrated to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: I'll mention the components for general awareness for consumers to help them design around these experiences (like the stepper and side nav)
created_at: 2025-05-09T21:47:34Z
author_association: CONTRIBUTOR
path: website/public/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png
user: login: KristinLBradley
body: Even though desktop view is most important to users of our products, I don't think it really matters if we list visual examples of screen sizes starting from small to large. So we may want to follow that order as it's traditional and to be consistent with the order of how we've listed the breakpoint names in the text.
created_at: 2025-05-09T21:50:12Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,47 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: Sorry, one more nit. I think these 2 sentences can go together vs. being treated as different paragraphs.
created_at: 2025-05-09T22:01:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: @dchyun Just wanted to comment, I find it a bit confusing too to not include values below 480px in the smallest view. However, I suppose as we start to use these in practice, we'll see if it's actually a problem or not and then could rethink if needed. (Just the view I'm taking currently.)
created_at: 2025-05-09T22:08:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,47 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: Good recommendation!
created_at: 2025-05-09T22:32:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! insight
+
+If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size.
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframe table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Diagram depicting "large", "medium", and "small" screen sizes displaying a varying number of columns in rows of content blocks.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
+
+### Responsiveness in Helios
+
+Helios has responsive behavior built into some components. These components include, but are not limited to, [SideNav](/components/side-nav) (lg), [Stepper Nav](/components/stepper/nav) (md) and [Pagination](/components/stepper/pagination) (lg). Knowing these details helps designers incorporate these behaviors seemlessly into their designs and creates cohesion between the system and product experiences.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: ```suggestion
Responsive behavior is already built into some Helios components. These components include, but are not limited to, [SideNav](/components/side-nav) (lg), [Stepper Nav](/components/stepper/nav) (md) and [Pagination](/components/stepper/pagination) (lg).
```
created_at: 2025-05-09T22:40:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! insight
+
+If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size.
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframe table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Diagram depicting "large", "medium", and "small" screen sizes displaying a varying number of columns in rows of content blocks.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
+
+### Responsiveness in Helios
+
+Helios has responsive behavior built into some components. These components include, but are not limited to, [SideNav](/components/side-nav) (lg), [Stepper Nav](/components/stepper/nav) (md) and [Pagination](/components/stepper/pagination) (lg). Knowing these details helps designers incorporate these behaviors seemlessly into their designs and creates cohesion between the system and product experiences.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: KristinLBradley
body: The last sentence didn't seem necessary to me.
created_at: 2025-05-09T22:40:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,41 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices.
+
+These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: I agree with your approach Kristin. My comment was more just around having a way of referring to those values. But we can see how things play out.
created_at: 2025-05-12T13:28:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: [Suggestion] I don't think it is accurate to say we don't expect designers to design mockups less than 479px. Most of the mobile frames in Figma are less than 480px. Our wireframes mobile views are at 390px. I would say we can probably remove this note. It may add more confusion around what sizes people should be creating mockups at for mobile. 
created_at: 2025-05-12T13:33:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! insight
+
+If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size.
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframe table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Diagram depicting "large", "medium", and "small" screen sizes displaying a varying number of columns in rows of content blocks.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
+
+### Responsiveness in Helios
+
+Responsive behavior is already built into some Helios components. These components include, but are not limited to:
+* [SideNav](/components/side-nav) (width collapses below lg breakpoint)
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: ```suggestion
* [App Side Nav](/components/app-side-nav) (width collapses below lg breakpoint)
```
[Suggestion] Should be updated to the new side nav component
created_at: 2025-05-12T13:35:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! insight
+
+If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size.
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframe table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Diagram depicting "large", "medium", and "small" screen sizes displaying a varying number of columns in rows of content blocks.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
+
+### Responsiveness in Helios
+
+Responsive behavior is already built into some Helios components. These components include, but are not limited to:
+* [SideNav](/components/side-nav) (width collapses below lg breakpoint)
+* [Stepper Nav](/components/stepper/nav) (layout shifts below sm breakpoint)
+* [Pagination](/components/stepper/pagination) (layout stacks below lg breakpoint)
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: ```suggestion
* [Pagination](/components/pagination) (layout stacks below lg breakpoint)
```
[Issue] Broken link
created_at: 2025-05-12T13:36:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! insight
+
+If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size.
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframe table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
+
+Redesigning across multiple breakpoints is often necessary for complex UIs, such as a landing page with cards arranged in a grid. As the viewport size decreases, both the position and content of the cards change, requiring nuanced designs across breakpoints. In such scenarios, designers should specify how the layout adjusts at the `sm`, `md`, and `lg` views.
+
+![Diagram depicting "large", "medium", and "small" screen sizes displaying a varying number of columns in rows of content blocks.](/assets/foundations/breakpoints/breakpoints-card-designs-shfting.png)
+
+### Responsiveness in Helios
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: ```suggestion
## Responsiveness in Helios
```
[Nit] This heading should probably be brought up one level
created_at: 2025-05-12T13:37:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: @majedelass @LilithJames-HDS thoughts? when we discussed this, [we agreed that designers should design at this viewport](https://docs.google.com/document/d/1gG-c9xUul3mwHvGUq7Z2NIWiM_-artjnjNCdGdrtLmI/edit?tab=t.0#heading=h.en743se5snt1) (480px). Should we review this decision?
created_at: 2025-05-12T14:25:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: > Most of the mobile frames in Figma are less than 480px

@dchyun sure, but because they're general purpose (and for mobile-app too). In our specific case, our applications are mainly (predominantly) [desktop-oriented](https://docs.google.com/document/d/1gG-c9xUul3mwHvGUq7Z2NIWiM_-artjnjNCdGdrtLmI/edit?tab=t.0#heading=h.hajyz1yaxat8), so having to design below that size becomes a bit of a futile exercise (that's [the conclusion we've reached](https://docs.google.com/document/d/1gG-c9xUul3mwHvGUq7Z2NIWiM_-artjnjNCdGdrtLmI/edit?tab=t.0#heading=h.en743se5snt1)).

> Our wireframes mobile views are at 390px

@majedelass @LilithJames-HDS something to review/reconsider with @andgen404 ?
created_at: 2025-05-12T14:34:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: Right now, no one designs for the mobile experience (at least not generally speaking), and so keeping it at 480px is fine. A couple of reasons why we chose 480: 
- Cloud UI uses this value as their "smallest" meaning that HCP values this number over, say 390 or even 320. This also means that adopting this value, and encouraging designers to start from here will create consistency across products from a standardization perspective.
- We are a "desktop first" company, even though we're trying to shift away from this thinking, it's our reality, meaning that smaller screens are less likely to be used for our products (390 is still pretty small).

If for some reason a product believes that anything other than 480 is needed (say 390 in addition to 480), nothing is stopping them from creating a custom value.

Lilith, would like to hear your thoughts if you have anything else to add too.
created_at: 2025-05-12T14:39:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: dchyun
body: Thanks for linking that decision in the memo. I missed that earlier. 
> Our wireframes mobile views are at 390px

I only referenced the Figma frames to show that _mostly_ the generic mobile views that the prototypes are built around are less than 480. 

My one design thought here is it's easier to design for the narrowest possible width than to design for a wider mobile width and have to worry what will happen when things shrink. I don't think what our prototypes are made at has to line up exactly with where our breakpoints are for every instance. Maybe for mobile it would be more helpful to design at a width below our breakpoint.

But that all said I totally get the "desktop first" idea, and I'm happy with whatever decision design lands on. Just wanted to see what our guidance was. 
created_at: 2025-05-12T15:03:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss{data-execute=false}
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: shleewhite
body: Just a side question: why does this code snippet need `{data-execute=false}` but not the one before?
created_at: 2025-05-12T15:10:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: I agree with the use of 480px. We have chatted about it and because of the nature and complexity of our products, we don't really expect end users to be working on tiny screens (if we did, we would likely have an app rather than just shoving everything into the smallest mobile experience). 480 gives designers enough visual real estate to imply how content wraps without losing the hierarchy 
created_at: 2025-05-12T15:14:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
+
+!!! insight
+
+If a custom value already exists that is relatively close to an established breakpoint, we recommend migrating it to the nearest standard breakpoint. This creates a consistent and predictable experience for the user as they work within (and across) the HashiCorp product suite.
+
+!!!
+
+## Designing with purpose
+
+Not all designs require redesigning at each breakpoint. Only when designs are considered complicated and/or constrained by UI elements should a designer take the time to show how they change as the viewport changes in size.
+
+For example, a UI featuring a table layout may not require changes for each breakpoint because the expected behavior is for the table to maintain its full width regardless of the breakpoint value. A design isn't necessary to elaborate this standard behavior.
+
+![Wireframe table shown expanding in size.](/assets/foundations/breakpoints/breakpoints-table-example.png)
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: shleewhite
body: ```suggestion
![](/assets/foundations/breakpoints/breakpoints-table-example.png)
```
created_at: 2025-05-12T15:26:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,16 @@
+---
+title: Breakpoints
+caption: Standardized breakpoints for different device widths.
+description: Different defined widths that help standardize responsive experiences across the HashiCorp product suite.
path: website/docs/foundations/breakpoints/index.md
user: login: LilithJames-HDS
body: ```suggestion
description: Breakpoints are defined width values that standardize responsive experiences across the HashiCorp product suite.
```

Sentence structure to match other foundations pages
created_at: 2025-05-12T15:47:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: This and the title being identical is a bit odd. What if we change this to something like "Viewport breakpoints" or "Standards for breakpoints" so there is some variety. Alternatively, we could remove this H2 like what's done on the Colors, Typography, and Accessibility pages.
created_at: 2025-05-12T15:51:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: ```suggestion
Breakpoints are viewport widths where layouts adjust to support responsive experiences on varied screen sizes and devices. These values are used to create utilities and helper components that standardize changes in UI at these widths.
```
created_at: 2025-05-12T16:00:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: I don't know that we use this language elsewhere, saying "Helios does XYZ" (treating Helios as an entity if that makes sense)?

```suggestion
There are five breakpoints in Helios: `sm`, `md`, `lg`, `xl`, and `xxl`.
```
or 
```suggestion
There are five HDS breakpoint values: `sm`, `md`, `lg`, `xl`, and `xxl`.
```
created_at: 2025-05-12T16:04:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss{data-execute=false}
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: didoo
body: You're right, I forgot to remove the others. Pushing a commit for this.
created_at: 2025-05-12T16:59:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: ```suggestion
_Note: the range 0-479px is intentionally left without a name. We don't anticipate designers needing to produce mockups for screen sizes below this width and from the audits conducted, Cloud UI has set a standard of 480px for the most narrow design. From a development perspective, in a mobile-first approach the range below 480px can be covered using default styles (overwritten via media queries for subsequent ranges).
_
```
created_at: 2025-05-12T17:05:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: ```suggestion
The provided breakpoints serve as a cohesive _starting_ point for design. Templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, a custom value may be added to enhance the user experience.
```
created_at: 2025-05-12T17:14:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,16 @@
+---
+title: Breakpoints
+caption: Standardized breakpoints for different device widths.
+description: Different defined widths that help standardize responsive experiences across the HashiCorp product suite.
path: website/docs/foundations/breakpoints/index.md
user: login: didoo
body: Maybe we could even remove `defined` from the sentence
created_at: 2025-05-12T18:26:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: In the second suggestion there is a typo/duplication?
created_at: 2025-05-12T18:27:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: didoo
body: "a custom value may be added" - as a designer, how do I "add" a custom value, in Figma? so maybe we could say something around "In such cases, a custom width value may be used..." 
created_at: 2025-05-12T18:29:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
+
+### Custom values
+
+The provided breakpoints serve as a cohesive _starting_ point for design, which is why templates have been provided in our [Patterns library](https://www.figma.com/design/5Pv32j4QiOOD8lkFTD1dxC/HDS-Patterns-v2.0?m=auto&node-id=71-11371&t=OvSfKLEJhHntQQZA-1) for this purpose. However, custom values may be necessary for specific use cases that these breakpoints do not cover. For example, if a team discovers that users with 2500px viewports are using a product, a nuanced approach to the UI at that screen size may be required. In such cases, an additional value can be added to enhance the user experience.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: That's a good note, that makes way more sense
created_at: 2025-05-12T19:16:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: LilithJames-HDS
body: Thanks for catching that — updated!
created_at: 2025-05-12T19:17:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to obtain the desired responsive layout, depending on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We provide also helpers in case you need to access the breakpoints names/values in JavaScript code.
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: KristinLBradley
body: ```suggestion
We also provide helpers in case you need to access the breakpoints names/values in JavaScript code.
```
created_at: 2025-05-12T22:10:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to obtain the desired responsive layout, depending on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We provide also helpers in case you need to access the breakpoints names/values in JavaScript code.
+
+You have access to the list of breakpoints' names using the `hdsBreakpointsNames` array:
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: KristinLBradley
body: ```suggestion
You have access to the list of breakpoint names using the `hdsBreakpointsNames` array:
```
created_at: 2025-05-12T22:17:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to obtain the desired responsive layout, depending on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We provide also helpers in case you need to access the breakpoints names/values in JavaScript code.
+
+You have access to the list of breakpoints' names using the `hdsBreakpointsNames` array:
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: KristinLBradley
body: Related: I think we may want to remove the "s" from "breakpoints" in the variable names: https://github.com/hashicorp/design-system/pull/2848/files#r2085611901
created_at: 2025-05-12T22:18:22Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to obtain the desired responsive layout, depending on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We provide also helpers in case you need to access the breakpoints names/values in JavaScript code.
+
+You have access to the list of breakpoints' names using the `hdsBreakpointsNames` array:
+
+```javascript{data-execute=false}
+import { hdsBreakpointsNames } from '@hashicorp/design-system-components/utils/hds-breakpoints';
+
+hdsBreakpointsNames.forEach(name => {
+  // do something with the breakpoints' names
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: KristinLBradley
body: ```suggestion
  // do something with the breakpoint names
```
created_at: 2025-05-12T22:19:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to obtain the desired responsive layout, depending on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We provide also helpers in case you need to access the breakpoints names/values in JavaScript code.
+
+You have access to the list of breakpoints' names using the `hdsBreakpointsNames` array:
+
+```javascript{data-execute=false}
+import { hdsBreakpointsNames } from '@hashicorp/design-system-components/utils/hds-breakpoints';
+
+hdsBreakpointsNames.forEach(name => {
+  // do something with the breakpoints' names
+});
+```
+
+You have also access to the list their names and values using the `hdsBreakpointsValues` map:
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: KristinLBradley
body: ```suggestion
You also have access to the list of breakpoint names and values using the `hdsBreakpointsValues` map:
```
created_at: 2025-05-12T22:20:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: jorytindall
body: [small suggestion]

```suggestion
In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography, spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
```
created_at: 2025-05-12T22:39:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to obtain the desired responsive layout, depending on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: jorytindall
body: [small suggestion]

```suggestion
Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to achieve the desired responsive layout, which depends on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
```
created_at: 2025-05-12T22:43:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: jorytindall
body: I'd advocate for removing this headline altogether and raising the subsequent headlines up to an H2.
created_at: 2025-05-12T22:45:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography and spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to obtain the desired responsive layout, depending on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We provide also helpers in case you need to access the breakpoints names/values in JavaScript code.
+
+You have access to the list of breakpoints' names using the `hdsBreakpointsNames` array:
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: didoo
body: Done.
created_at: 2025-05-13T08:36:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,48 @@
+## Breakpoints
+
+Breakpoints define specific viewport widths where the layout adjusts to support responsive experiences across screen sizes and devices. These values are then used to create utilities and helper components to standardize changes of the UI at different viewport sizes.
+
+### The ranges
+
+Helios defines five breakpoints: `sm`, `md`, `lg`, `xl`, and `xxl`.
+
+| Name   | Value        | Application                   |
+| ------ | ------------ | ----------------------------- |
+| sm     | 480px        | 480 → 767                     |
+| md     | 768px        | 768 → 1087                    |
+| lg     | 1088px       | 1088 → 1439                   |
+| xl     | 1440px       | 1440 → 1919                   |
+| xxl    | 1920px       | 1920 and up                   |
+
+The breakpoint name refers to a range of pixel values, not just the starting value. For example, the `sm` breakpoint refers to widths between 480px and 767px. This helps simplify the language around what these ranges mean when designing and increases the flexibility in implementation.
+
+_Note: the range 0-479px is intentionally left without a name: from a design perspective, we don't expect designers to produce mockups for such small screen sizes; from a development perspective, in a mobile-first approach that range can be covered using default styles (overwritten via media queries for subsequent ranges)._
path: website/docs/foundations/breakpoints/partials/guidelines/guidelines.md
user: login: majedelass
body: Formatting is slightly off for the italics, so I updated it. Thanks for this suggestion.
created_at: 2025-05-13T12:06:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,119 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography, spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to achieve the desired responsive layout, which depends on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: MelSumner
body: ```suggestion
Of course, these are oversimplified examples. In your implementation, you will have to choose which mixin is best suited to achieve the desired responsive layout. This will  depend on the design specifications, the context of the layout within the page, and how it relates with other UI elements.
```
created_at: 2025-05-13T21:21:19Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,119 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography, spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to achieve the desired responsive layout, which depends on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We also provide helpers in case you need to access the breakpoints names/values in JavaScript code.
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: MelSumner
body: (Question, non-blocker) How often do we expect this to happen? Should the language reflect whether or not this is a good idea? In other places we've said things like, "should you need to" which is more of an indicator that _it's there but use with caution_. 
created_at: 2025-05-13T21:23:34Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,119 @@
+## How to use the breakpoints
+
+In [responsive design](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design) it's common practice to define specific media queries in CSS that can be used to control not only the layout of the entire page and its parts, but also other aspects of a UI like typography, spacing, the rendering of decorative elements, the resolution of media assets, and much more. These media queries are built using CSS `@media` declarations in combination with a set of standard breakpoints.
+
+Our design system defines [breakpoint values](/foundations/breakpoints#the-ranges) based on browser viewport widths. The intervals between these breakpoints create distinct ranges, which can be used with the [Sass](/foundations/breakpoints?tab=code#sass) and [JavaScript](/foundations/breakpoints?tab=code#javascript) helpers to implement responsive designs for our applications.
+
+### Sass
+
+To use the Sass helpers provided by the design system, you must import the corresponding Sass file (via `@use`, [as recommended](https://sass-lang.com/documentation/at-rules/use/#differences-from-import)) from the `@hashicorp/design-system-components` package:
+
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+```
+
+!!! info
+
+If you are not able to import the file using the declaration above, [contact the Design Systems Team](/about/support) for support.
+
+!!!
+
+Once the file is imported, you will have access to the Sass helpers described below.
+
+#### Mixins
+
+Sass mixins offer the simplest, most efficient way to implement responsive layouts using the standard breakpoints defined in our system. We provide three different mixins:
+
+- `hds-breakpoint-above($name)` - for media queries that apply to a viewport range **above** a certain breakpoint (useful for a mobile-first approach)
+- `hds-breakpoint-below($name)` - for media queries that apply to a viewport range **below** a certain breakpoint (useful for a desktop-first approach)
+- `hds-breakpoint-between($lower, $upper)` - for media queries that apply to a viewport range **between** two breakpoints
+
+Here is an example of how the mixins could be used in a mobile-first responsive layout:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior, that covers the range 0px–767px
+  display: flex;
+  direction: column;
+  gap: 1rem;
+
+  // at 768px the layout changes, from a vertical stack to an horizontal one
+  @include hds-breakpoint-above('md') {
+    direction: row;
+  }
+
+  // at larger viewports we increase the spacing between the items
+  @include hds-breakpoint-above('xl') {
+    gap: 2rem;
+  }
+}
+```
+
+The same layout could be achieved using a desktop-first approach in a similar way:
+
+```scss
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+.my-responsive-layout {
+  // this is the default behavior
+  display: flex;
+  direction: row;
+  gap: 2rem;
+
+  // at smaller viewports we decrease the spacing between the items
+  @include hds-breakpoint-below('xl') {
+    gap: 1rem;
+  }
+
+  // at 768px the layout changes, from an horizontal stack to a vertical one
+  @include hds-breakpoint-below('md') {
+    direction: column;
+  }
+}
+```
+
+Of course, these are oversimplified examples. In your implementation, you will have to choose which of the provided mixins are better suited to achieve the desired responsive layout, which depends on the design specifications, the context of where the layout lives in the page, and how it relates with the other UI elements.
+
+#### Key/Value Map
+
+For special use cases, we also provide a Sass map–`$hds-breakpoints`–which is a lower level helper than the mixins. Here's an example of how this map could be used:
+
+```scss
+// explicit import of `map` module (required by Sass)
+@use "sass:map";
+// from @hashicorp/design-system-components package
+@use "mixins/breakpoints" as *;
+
+@each $name, $size in $hds-breakpoints {
+  .my-custom-breakpoint-class--#{$name} {
+    // here you have access to the breakpoint name and its value (width in px)
+  }
+}
+```
+
+### JavaScript
+
+We also provide helpers in case you need to access the breakpoints names/values in JavaScript code.
path: website/docs/foundations/breakpoints/partials/code/how-to-use.md
user: login: didoo
body: There's nothing "dangerous" in them using the breakpoints in JS, it depends on the context where they need it (meet them where they are). There are use cases where controlling responsive behaviour in JS is inevitable (and in fact, that's what we do ourselves in the AppHeader and AppSideNav/SideNav components). 
created_at: 2025-05-13T21:27:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -21,6 +21,9 @@ This is the full-fledged component (responsive and animated).
   <C.Property @name="isMinimized" @type="boolean" @default="false">
     Controls if the App Side Nav is rendered collapsed or expanded when initialized. This allows an application to preserve the collapsed/expanded state across sessions. After the initial render, this argument is altered based on user interactions (collapse/expand the App Side Nav or resize the window) and it is not a suitable way of controlling the App Side Nav state from outside after render (it’s an internal state).
   </C.Property>
+  <C.Property @name="breakpoint" @type="string" @default="1088px">
+    Set a custom breakpoint to control the page width at which the UI switches from displaying the mobile/small view vs. the desktop/view.
path: website/docs/components/app-side-nav/partials/code/component-api.md
user: login: KristinLBradley
body: ```suggestion
    Set a custom breakpoint to control the page width at which the UI switches from displaying the mobile/small view vs. the desktop/large view.
```
created_at: 2025-05-13T21:50:27Z
author_association: CONTRIBUTOR

PR comments:
user: login: vercel[bot]
created_at: 2025-05-06T12:28:48Z
body: [vc]: #hpshaAMp7NH/EXh23wDZitd8geA3FJX4ia+EPYZc25s=:eyJpc01vbm9yZXBvIjp0cnVlLCJ0eXBlIjoiZ2l0aHViIiwicHJvamVjdHMiOlt7Im5hbWUiOiJoZHMtc2hvd2Nhc2UiLCJyb290RGlyZWN0b3J5Ijoic2hvd2Nhc2UiLCJpbnNwZWN0b3JVcmwiOiJodHRwczovL3ZlcmNlbC5jb20vaGFzaGljb3JwL2hkcy1zaG93Y2FzZS80SnN5alVXTDZGekZjUGpIUmd6U1lXbjIxZTI3IiwicHJldmlld1VybCI6Imhkcy1zaG93Y2FzZS1naXQtYnJlYWtwb2ludHMtaGFzaGljb3JwLnZlcmNlbC5hcHAiLCJuZXh0Q29tbWl0U3RhdHVzIjoiREVQTE9ZRUQifSx7Im5hbWUiOiJoZHMtd2Vic2l0ZSIsInJvb3REaXJlY3RvcnkiOiJ3ZWJzaXRlIiwiaW5zcGVjdG9yVXJsIjoiaHR0cHM6Ly92ZXJjZWwuY29tL2hhc2hpY29ycC9oZHMtd2Vic2l0ZS82VE00Y29QZDJzMWhHcHRkWVhBTlZMWjY0aUZTIiwicHJldmlld1VybCI6Imhkcy13ZWJzaXRlLWdpdC1icmVha3BvaW50cy1oYXNoaWNvcnAudmVyY2VsLmFwcCIsIm5leHRDb21taXRTdGF0dXMiOiJERVBMT1lFRCJ9XX0=
**The latest updates on your projects**. Learn more about [Vercel for Git ↗︎](https://vercel.link/github-learn-more)

| Name | Status | Preview | Updated (UTC) |
| :--- | :----- | :------ | :------ |
| **hds-showcase** | ✅ Ready ([Inspect](https://vercel.com/hashicorp/hds-showcase/4JsyjUWL6FzFcPjHRgzSYWn21e27)) | [Visit Preview](https://hds-showcase-git-breakpoints-hashicorp.vercel.app) | May 14, 2025 6:41am |
| **hds-website** | ✅ Ready ([Inspect](https://vercel.com/hashicorp/hds-website/6TM4coPd2s1hGptdYXANVLZ64iFS)) | [Visit Preview](https://hds-website-git-breakpoints-hashicorp.vercel.app) | May 14, 2025 6:41am |



author_association: NONE
user: login: didoo
created_at: 2025-05-12T14:27:36Z
body: @shleewhite @KristinLBradley @dchyun I have added the documentation for the "code" tab: https://hds-website-git-breakpoints-hashicorp.vercel.app/foundations/breakpoints?tab=code

Can you have a look and tell me what you think? If, as developer, it's clear what you're supposed to do, to use our breakpoints?
author_association: CONTRIBUTOR
user: login: KristinLBradley
created_at: 2025-05-12T22:24:12Z
body: > @shleewhite @KristinLBradley @dchyun I have added the documentation for the "code" tab: https://hds-website-git-breakpoints-hashicorp.vercel.app/foundations/breakpoints?tab=code
> 
> Can you have a look and tell me what you think? If, as developer, it's clear what you're supposed to do, to use our breakpoints?

@didoo I think it's very clear overall. I just added a few minor suggested edits and a question/suggestion for possibly changing some variable names.
author_association: CONTRIBUTOR
user: login: didoo
created_at: 2025-05-13T21:16:51Z
body: @jorytindall @shleewhite @KristinLBradley @dchyun I had to push a couple of extra commit, any of you can re-approve? thanks
author_association: CONTRIBUTOR
user: login: dchyun
created_at: 2025-05-14T16:01:16Z
body: @didoo please update the base of this to the new `release/website-4-20` branch. We will be merging all docs updates into this branch, and then merging it into main post-release. 
author_association: CONTRIBUTOR
user: login: didoo
created_at: 2025-05-14T16:33:46Z
body: @dchyun done. I need re-approval now.
author_association: CONTRIBUTOR