[Docs] Spacing & layout - content restructure (2 of 5) #5573
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: julauxen <[email protected]>
|
oliverHPE
reviewed
Nov 20, 2025
Comment on lines
11
to
14
| Spacing guides users' eyes through the page, helping them understand the relationships | ||
| between different elements. The HPE Design System minimizes use of borders to separate | ||
| content. Instead spacing, typography, and background color are combined to create visual | ||
| hierarchy. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Spacing guides users' eyes through the page, helping them understand the relationships | |
| between different elements. The HPE Design System minimizes use of borders to separate | |
| content. Instead spacing, typography, and background color are combined to create visual | |
| hierarchy. | |
| Effective spacing guides a user's eye through the interface, making it easier to understand how elements relate to one another. The HPE Design System minimizes use of borders to separate | |
| content. Instead spacing, typography, and background color are combined to create clear visual | |
| hierarchy. |
oliverHPE
reviewed
Nov 20, 2025
Comment on lines
18
to
20
| The following spacing scale may be applied to create separation between [content | ||
| containers](/insert-link-when-available) (gap), between a content container's boundary | ||
| and its content (padding), and within content subsections (gap). |
Collaborator
There was a problem hiding this comment.
Suggested change
| The following spacing scale may be applied to create separation between [content | |
| containers](/insert-link-when-available) (gap), between a content container's boundary | |
| and its content (padding), and within content subsections (gap). | |
| Use spacing to: | |
| - Create separation between content containers (gaps) | |
| - Set space between a container’s boundary and its content (padding) | |
| - Define spacing within subsections of content (gaps) |
julauxen
reviewed
Nov 20, 2025
Comment on lines
22
to
34
| <Notification | ||
| alignSelf="start" | ||
| status="warning" | ||
| title="Avoid use of margin" | ||
| message={ | ||
| <Paragraph margin="none"> | ||
| Use of margin can lead to unpredictable responsive and/or adaptive layouts | ||
| and should be used with caution, if not avoided. All layouts may be | ||
| achieved using gap and padding, resulting in more flexible, predictable, | ||
| and maintainable layouts. | ||
| </Paragraph> | ||
| } | ||
| /> |
Collaborator
There was a problem hiding this comment.
Could we add this in a do's and don't format, under the "spacing best practices" section?
If we want to present this as an "avoid" instead of a don't we can introduce this granularity like material does:
Collaborator
Author
There was a problem hiding this comment.
I like this idea. Do you have a supporting graphic / illustration in mind? I am blanking on a illustrative scenario at the moment.
Comment on lines
6
to
9
| Spacing sizes are a subset of the [scale system](/foundation/scale-system) | ||
| using proximity principles to define relationships between content and create | ||
| hierarchy within a page. Spacing design tokens define the padding within, margin | ||
| around, or gap between content. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Spacing sizes are a subset of the [scale system](/foundation/scale-system) | |
| using proximity principles to define relationships between content and create | |
| hierarchy within a page. Spacing design tokens define the padding within, margin | |
| around, or gap between content. | |
| Spacing sizes are a subset of the [scale system](/foundation/scale-system), | |
| supporting proximity principles to shape relationships between content and establish hierarchy on a page. These principles are applied through [spacing tokens](/design-tokens/layout-and-spacing/spacing), which define the padding within, margin | |
| around, or gap between content. |
oliverHPE
reviewed
Nov 20, 2025
Comment on lines
63
to
65
| message: `Use spacing design tokens to style element-level components. | ||
| Instead, use component-specific tokens or element tokens which ensure | ||
| correct sizing of elements across screen sizes.`, |
Collaborator
There was a problem hiding this comment.
Suggested change
| message: `Use spacing design tokens to style element-level components. | |
| Instead, use component-specific tokens or element tokens which ensure | |
| correct sizing of elements across screen sizes.`, | |
| message: `Use spacing design tokens to style element-level components. | |
| Instead, use component-specific tokens or [element tokens](https://design-system.hpe.design/design-tokens/element) which ensure | |
| correct sizing of elements across screen sizes.`, |
oliverHPE
reviewed
Nov 20, 2025
Comment on lines
28
to
31
| Use of margin can lead to unpredictable responsive and/or adaptive layouts | ||
| and should be used with caution, if not avoided. All layouts may be | ||
| achieved using gap and padding, resulting in more flexible, predictable, | ||
| and maintainable layouts. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Use of margin can lead to unpredictable responsive and/or adaptive layouts | |
| and should be used with caution, if not avoided. All layouts may be | |
| achieved using gap and padding, resulting in more flexible, predictable, | |
| and maintainable layouts. | |
| Relying on margin can lead to unpredictable responsive and/or adaptive layouts and should be used with caution, if at all. Most layouts can be achieved using only gap and padding, resulting in more flexible, predictable, and maintainable designs. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Deploy Preview
What does this PR do?
This is the second of a series of chained PRs building upon #5521. The PRs should be reviewed and merged in order.
This pull request reorganizes and expands the foundation documentation structure for the design system, introducing a new "Spacing" section and improving the categorization of related content. The main changes include moving and reclassifying the "T-shirt sizing" and "Scale system" cards under a new "Layout" category, adding a new "Spacing" card and related documentation, and implementing supporting example components for the new section.
Foundation structure and categorization improvements:
New documentation and examples for spacing:
spacing.mdxdocumentation page, providing guidance, best practices, and interactive examples for spacing, including a visual scale and a call-to-action for design tokens.SpacingScale, which visually displays the spacing scale;SpacingTokensCTA, a button linking to spacing design tokens; andSpacingBestPractices, for illustrating best and worst practices. These are now exported and used in the new documentation. [1] [2] [3]Supporting exports and cleanup:
What are the relevant issues?
Where should the reviewer start?
https://deploy-preview-5573--keen-mayer-a86c8b.netlify.app/foundation/spacing
How should this be manually tested?
Any background context you want to provide?
Screenshots (if appropriate)
Should this PR be mentioned in Design System updates?
Is this change backwards compatible or is it a breaking change?