Files

T

claude 0730557624 Initial mirror of the HPE Design System

Readable mirror of https://design-system.hpe.design, sourced from
github.com/grommet/hpe-design-system (Apache-2.0) at commit 567c4d5
(2026-07-16).

The upstream site is a client-rendered Next.js export with no sitemap; it
returns a 1.5 KB empty shell to curl. This repo is the same guidance in plain
Markdown with every value resolved, plus the assets checked in.

Docs: scope and authority model, brand foundations with resolved color and
spacing tables, the design token tiers and version map, UI copy rules,
accessibility conformance and the responsibility split, the component and
template inventory, and an adoption/review checklist.

Assets: 452 SVG icons, 5 HPE and Aruba word-marks, 282 documentation graphics.

HOWTO-mirror-the-design-system.md is a verified runbook for rebuilding this
from scratch against a newer upstream.

Colors were resolved programmatically, not transcribed: token JSON stores
references, not values.

Apache-2.0 upstream. Note that it covers copyright, not trademark; Brand
Central remains authoritative for the HPE marks.

2026-07-30 08:34:50 -04:00

6.9 KiB

Raw Permalink Blame History

03 — Design tokens

Design tokens are the delivery mechanism for HPE's visual style. They are the reason a product can adopt a brand refresh with a version bump instead of a redesign, and they are the answer to "how do we do this without React."

What a token is

A named value carrying its intended usage. Four properties, two required:

Property	Required	Example
Name	yes	`hpe.color.background.back`
Value	yes	`#f7f7f7`
Type	no	color, dimension, shadow
Description	no	how the token should be used

The point is that consumers reference the name, never the value. When HPE updates the value, every consumer pointing at the name picks it up on upgrade.

The three tiers

Tokens are layered by specificity. The rule for consuming them:

Begin with the most specific token level available. Look first to see if a component token exists. If not available, use semantic tokens as a fallback.

Primitive

The raw palette. Names describe the value, not where to use it. Values are always concrete CSS values: a hex code, a pixel, a rem.

hpe.base.color.green.600   →  #01a982
hpe.base.dimension.400     →  16

Primitive tokens must not be used directly in a product. They exist to be referenced by the tiers above.

Semantic

Names say when and where to apply. Values reference a primitive or another semantic token.

hpe.color.background.back   →  {base.color.grey.50} in light, {base.color.grey.1300} in dark
hpe.spacing.large           →  differs by viewport width

This is where context-dependence lives. One semantic name resolves to different values in light versus dark mode, or wide versus narrow viewport. That is the whole mechanism behind free dark mode.

Component

Decisions for a single component or a family. Values reference any lower tier.

hpe.button.primary.rest.background

Component tokens encode state (rest, hover, active, disabled, focus) as part of the name. See the site's design-tokens/component-states page for the state model.

Token file layout in the repo

packages/hpe-design-tokens/tokens/:

primitive/ — primitives.default.json, plus pinned .v0 and .v1 files
semantic/ — color.light.json, color.dark.json, dimension.default.json, dimension.small.json, global.default.json, plus .v0 and .v1 variants
component/ — component.default.json, element.default.json, plus variants

Two things to notice. First, the old major versions are kept in-tree rather than only in git history, which is what makes opt-in-by-mode work in Figma. Second, dimension.small.json alongside dimension.default.json is the responsive mechanism: the same semantic dimension name resolves smaller on narrow viewports.

There is also a deprecated.* namespace inside the primitives, which is where superseded values go. deprecated.base.color.green.400 is #17eba0 where the live base.color.green.400 is #00e0af, so a stale reference will render a visibly different green.

Versioning

hpe-design-tokens follows semver with one adaptation: a major version can be triggered by a brand change alone, with no API break.

Increment	Trigger
MAJOR	Significant change to HPE's brand expression, or an incompatible API change
MINOR	New token, or a small expected value change (darkening a text color after user testing)
PATCH	Backward-compatible fix (a typo in a value, a color corrected to meet contrast)

The reason a brand change alone forces a major: if service A is on v1 and service B is on v2, the two will not look like the same company. The major version is the signal that a mismatch exists.

Version map

Tokens	Theme	Period	Notes
`^2.0.0` "v2-Landmark"	`grommet-theme-hpe` 8.x	Oct 2025 to present	Landmark palette, HPE Graphik font face. Default in the Figma V2 library. Current release 2.2.3
`^1.0.0`	`grommet-theme-hpe` 6.x–7.x	Feb 2025 to Sep 2025	Opt-in via "v1" modes in Figma
`^0.9.0`	`grommet-theme-hpe` 5.x	May 2023 to Jan 2025	Opt-in via "v0" modes in Figma

v2-Landmark is a breaking change from v1. Migration guides live in the GitHub wikis for both hpe-design-system and grommet-theme-hpe.

v0.9.0 to v1.0.0 had no breaking API changes in the tokens (only value changes), but grommet-theme-hpe v5 to v7 did break, and the migration is documented in two steps: 5.x to 6.x for visual treatments, then 6.x to 7.x for expanded t-shirt sizing.

The recommended adoption trick

For a product adopting tokens for the first time, the docs recommend mapping local components to v0.9.0 tokens first. That reaches style parity with the product's existing look, so QA is comparing against something familiar and any diff is a real bug rather than an intended restyle. Only then upgrade forward.

This is worth remembering. It converts one large risky change into two smaller ones with a verifiable checkpoint between them.

Consuming tokens

React plus Grommet: install grommet-theme-hpe. Tokens, fonts, and component defaults come with it. This is the environment the design system targets and the one with the most examples.
Anything else: consume hpe-design-tokens directly. It is published to npm in multiple output formats and is tech-agnostic. The site page design-tokens/using-design-tokens-in-code covers the formats.
Figma: tokens appear as Figma variables. design-tokens/using-design- tokens-in-figma covers setup, and the "Themes and modes" Figma file covers switching between v0, v1, and v2 modes.

The tokens are built with Style Dictionary. The repo has custom transforms and formats under packages/hpe-design-tokens/src/, plus a apps/design-tokens-manager application and a contracts/schemas directory that validates token structure.

A detail worth knowing about units

Dimension primitives are stored as unitless numbers (base.dimension.400 is the number 16, not "16px"). The numberToDimension transform assigns units at build time, and it does not treat them all the same:

fontSize and lineHeight are divided by 16 and emitted as rem
everything else (spacing, radius, padding, width, height, border width, breakpoints) is emitted as px

So type scales with the user's browser font setting and layout does not. If you read a raw token JSON value and see a bare number, that is why.

hpe-design-system-codemods (v0.2.1) automates some migration edits.

Open questions

Which output formats does hpe-design-tokens actually publish (CSS custom properties, SCSS, JSON, Swift, XML)? Read the package before promising a non-web team it is covered.
Is there a deprecation policy with a stated support window for a major version, or does an old major just stop receiving fixes?
How long did a real product take to migrate v1 to v2-Landmark? A worked example would size the effort better than the migration guide does.

6.9 KiB Raw Permalink Blame History Unescape Escape