claude
0730557624
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.
169 lines
6.9 KiB
Markdown
169 lines
6.9 KiB
Markdown
# 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.
|