Migrating from HPE Theme 6.x to 7.x
grommet-theme-hpe v7.0.0 provides designers and developers greater flexibility for layouts by introducing expanded sizing options.
An expanded range of t-shirt sizes for spacing, height, and widths addresses layout situations where "medium" might have been too narrow and "large" too wide. With v7's greater selection of sizes, you can find a t-shirt size that fits "just right."
-
Expanded sizing options: Addresses product teams feedback by offering an expanded range of t-shirt sizes for spacing, height, and width.
-
Introduces in-between steps which address gaps in the current scale. --> Makes desired design layouts easier to execute.
-
Has parity with existing scale which means that all designs may be recreated with the new scale without any layout shifts.
-
New
medium= currentmedium; however, rest of t-shirt sizes will need to be mapped to achieve design parity. -
Every t-shirt size may be composed by smaller t-shirt sizes and/or divided into halves, thirds, quarters, ... 12ths, etc. (e.g.
small+small=large, orxsmall+xsmall+xsmall=large, or evenmedium+xsmall=large)
-
-
Design-to-code parity: Completes alignment for t-shirt size values in grommet-theme-hpe with those defined in Figma and hpe-design-tokens v1, ensuring consistency across design and development.
-
Resolves temporary design-code discrepancy: To ease adoption for existing applications, v6 focused solely on visual style updates. Expanded t-shirt sizes were omitted, as they introduce breaking changes in the form of layout shifts. This created a temporary misalignment between Figma and
grommet-theme-hpe. With broad adoption of the latest Figma components, v7 addresses this misalignment debt. -
Focused migration scope: The scope of changes in v7 is limited to t-shirt sizing and some accessibility improvements. The limited scope is intended to help teams assess any layout regressions and review pull requests with greater confidence. To achieve layout parity, t-shirt sizes need to be re-mapped (e.g. replace existing "small" with new "xsmall").
-
Codemod migration assist: Script available providing automated t-shirt size remapping.
Modify the following in your package.json:
// package.json
...
"dependencies": {
...
"grommet": "^2.49.0", // peerDependency of grommet-theme-hpe v7
"grommet-theme-hpe": "^7.0.0",
...
}
To achieve layout parity, old t-shirt sizes need to map to new t-shirt sizes.
To aid migration, this automated codemod transforms your existing code to use the new t-shirt sizes. This tool handles the majority of migration scenarios automatically, including complex nested structures and special component props.
After running the codemod, check for:
-
Custom size variables - Variables containing breakpoint names vs. actual size values.
-
Visual regression - Test your application to ensure the new sizes meet design expectations.
Lastly, these regex patterns may be helpful in addition to the codemod.
The new scale has parity with the existing scale, meaning that all designs may be recreated with the new scale without any layout shifts (excluding border widths >6px, which have been deprecated). Review content layouts with existing tests and quality assurance processes.
Used for: pad, margin, gap, thickness
| Current | New | Value |
|---|---|---|
| hair | hair | 1px |
| xxsmall | 5xsmall | 3px |
| -- | 4xsmall | 4px |
| xsmall | 3xsmall | 6px |
| -- | xxsmall | 8px |
| small | xsmall | 12px |
| -- | small | 16px |
| medium | medium | 24px |
| -- | large | 32px |
| large | xlarge | 48px |
| -- | xxlarge | 64px |
| xlarge | 3xlarge | 96px |
Used for: height, width, size, columns, rows
| Current | New | Value |
|---|---|---|
| xxsmall | 5xsmall | 48px |
| -- | 4xsmall | 64px |
| xsmall | 3xsmall | 96px |
| -- | xxsmall | 128px |
| small | xsmall | 192px |
| -- | small | 256px |
| medium | medium | 384px |
| -- | large | 512px |
| large | xlarge | 768px |
| -- | xxlarge | 1024px |
| xlarge | -- | 1152px (value eliminated because it doesn't follow formula) |
| xxlarge | 3xlarge | 1536px |
Used for: round
| Current | New | Value |
|---|---|---|
| none | none | 0px |
| hair | hair | 1px |
| xxsmall | -- | 3px |
| -- | xxsmall | 4px |
| xsmall | xsmall | 6px |
| -- | small | 8px |
| small | medium | 12px |
| -- | large | 16px |
| medium | xlarge | 24px |
| -- | xxlarge | 32px |
| large | -- | 48px |
| -- | -- | 64px |
| xlarge | -- | 96px |
| full | full | 9999px |
Used for: border
| Current | New | Value |
|---|---|---|
| -- | none | 0px |
| xsmall | xsmall | 1px |
| small | small | 2px |
| medium | medium | 4px |
| -- | large | 6px |
| large | -- | 12px |
| xlarge | -- | 24px |
| -- | default | 1px |
This step will identify and transform t-shirt sizes passed to the following Grommet component props:
Spacing props: pad, margin, gap, thickness
Container props: height, width, size, columns, rows
Border props: border
Radius props: round
See what the codemod transforms for full detail.
Run t-shirt size migration script.
# From project's root
npx hpe-design-system-codemods migrate-theme-v6-to-v7 src/ <options>
See options documentation.
Apply code formatter to align quotes and other formatting with your project's preferences.
npx prettier --write src/
This step will help identify areas where manual intervention may be needed in addition to the automatic transformation.
The --scan option will:
-
Identify t-shirt size usage that may require manual review - focusing on variables, complex patterns, and edge cases that the automatic transformation may not handle properly.
-
Will not make any changes to your files.
See what the codemod does not transform for full detail.
npx grommet-codemod migrate-tshirt-sizes src/ --scan
The codemod won’t catch every case. Use these regex searches in VS Code (toggle the .* regex option in the search bar) to find likely problem areas:
- Variables holding t-shirt sizes
(const|let|var)\s+\w+\s*=\s*['"](x?small|medium|large|xlarge)['"]
- Object properties with ambiguous names
\{\s*\w+\s*:\s*['"](x?small|medium|large|xlarge)['"]
- Destructuring with default values
\{\s*\w+\s*=\s*['"](x?small|medium|large|xlarge)['"]
- Conditional expressions with non-prop variables
\?\s*['"](x?small|medium|large|xlarge)['"]\s*:\s*['"](x?small|medium|large|xlarge)['"]
These searches won’t always mean something needs changing—but they’ll quickly surface spots that deserve a second look.