@hpe-web/design-tokens
v2.0.0
Published
HPE Design System design tokens — CSS custom properties, DTCG 2025.10 source, locale overrides, and Style Dictionary transforms. Three-tier aliased architecture (primitive → semantic → component) preserved end-to-end as CSS var() chains.
Maintainers
eamirianReadme
@hpe-web/design-tokens
HPE Design System design tokens — CSS custom properties, DTCG source, locale overrides, and Style Dictionary transforms. Three-tier token architecture (primitive → semantic → component) preserved end-to-end as CSS var() chains.
What's new
2.0.0 — first release off the new Figma-REST pipeline
Token values now track current Figma directly (Supernova retired). Font sizes, line-heights, spacing, and non-heading vars from 1.3.1 are unchanged — but there are breaking changes, so review before upgrading:
- ⚠️ Breaking — heading
.defaultremoved. All--hpe-web-heading-h{1..6}-default-*properties are gone; Figma split heading styles into light/medium. Migrate--hpe-web-heading-h2-default-font-size→…-h2-light-font-size(or-medium-). - All component families now ship.
card,marquee,logo,live-player,content-block,global-navjoinbutton(23 new), e.g.--hpe-web-card-layout-gap-x,--hpe-web-marquee-gap-y. - Full dark-theme coverage —
tokens.dark.cssgrows 67 → 258 vars (component states, backgrounds, gradients now resolve in dark mode). - A few value updates from current Figma:
criticalred andprimary-stronggreen darkened a step;button-linkrest/hover color states + hover weight refined;radius-fullnow aliases a static. - Token names lose spaces (
content block→content-block), and the DTCG source pathsrc/component/button.json→src/component/component.json. CSS consumers are unaffected by both.
Font-size (rem), line-height (unitless ratio), letter-spacing (em), and spacing are emitted exactly as in 1.3.1.
Install
npm install @hpe-web/design-tokensUsage
CSS (recommended)
Load the base file and any overrides your app needs. The cascade handles viewport, theme, and locale simultaneously.
<!-- Required -->
<link rel="stylesheet" href="node_modules/@hpe-web/design-tokens/css/tokens.css">
<!-- Optional -->
<link rel="stylesheet" href="node_modules/@hpe-web/design-tokens/css/tokens.dark.css">
<link rel="stylesheet" href="node_modules/@hpe-web/design-tokens/css/tokens.md-lg.css">
<link rel="stylesheet" href="node_modules/@hpe-web/design-tokens/css/tokens.xl.css">
<!-- Locales (if your app serves multiple languages) -->
<link rel="stylesheet" href="node_modules/@hpe-web/design-tokens/css/locales/de.tokens.css">
<link rel="stylesheet" href="node_modules/@hpe-web/design-tokens/css/fonts/de.css">| File | Contents | Applied when |
|------|----------|-------------|
| tokens.css | All tokens — xs-sm base, light theme | Always |
| tokens.dark.css | Dark theme color overrides | [data-theme="dark"] |
| tokens.md-lg.css | Typography + border-radius overrides | @media (min-width: 992px) |
| tokens.xl.css | Typography + border-radius overrides | @media (min-width: 1600px) |
| locales/{lang}.tokens.css | Font-size + font-family overrides | [lang="xx"] |
| fonts/{lang}.css | @font-face declarations | Always (locale-specific) |
Then use tokens in your CSS:
.card {
background: var(--hpe-web-color-background-card);
padding: var(--hpe-web-space-medium);
border-radius: var(--hpe-web-border-radius-medium);
font-size: var(--hpe-web-text-medium-font-size);
}No breakpoint logic needed in component CSS. Token values shift automatically as viewport, theme, and lang attributes change.
Dark mode:
<body data-theme="dark">…</body>Locale switching:
<html lang="de">…</html>Token audit workflow (Figma parity + 1:1 mapping)
When auditing component styles against Figma, use this workflow to guarantee Light/Dark parity and one canonical mapping per variable.
- Start from Figma variables for both Light and Dark modes.
- Resolve each variable to DTCG source in
src/primitive,src/semantic, orsrc/component. - Validate the generated CSS property in
docs/tokens/token-mapping.doc.md. - Enforce canonical 1:1 mapping: one Figma variable maps to one CSS custom property.
- Enforce mode parity for colors: semantic aliases must exist in both
color.light.jsonandcolor.dark.json. - Record unresolved gaps in
docs/tokens/missing-tokens.doc.mdwith:
- Light value
- Dark value
- Canonical target CSS property
- Mode coverage status (
Light only,Dark only,Light+Dark missing)
Audit Definition of Done:
- Every Figma variable used by a component has exactly one canonical CSS property.
- Every color variable has Light and Dark semantic coverage.
- Component CSS uses canonical token variables only (no raw fallback values for tokenized properties).
- Missing token backlog has no unresolved rows for the audited component.
Static metadata
All three metadata files live in static/:
import breakpoints from '@hpe-web/design-tokens/src/breakpoints.json' assert { type: 'json' };
// { values: { xs: '0px', md: '992px', xl: '1600px' },
// ranges: { 'md-lg': { mediaQuery: '(min-width: 992px)' }, ... } }
import locales from '@hpe-web/design-tokens/src/locales.json' assert { type: 'json' };
// locales.de.coefficient.display === 0.75
// locales.ja.minFontSize === '14px'
import fonts from '@hpe-web/design-tokens/src/fonts.json' assert { type: 'json' };breakpoints.json is generated from DTCG token values at build time. fonts.json and locales.json are hand-maintained. All three are for tooling and pipeline scripts — the browser gets everything it needs from the CSS files.
Bring your own Style Dictionary
For custom output formats (AEM, native, SCSS), run your own SD pipeline against our DTCG source:
import StyleDictionary from 'style-dictionary';
import { lineHeightUnitless, letterSpacingEm } from '@hpe-web/design-tokens/transforms';
const sd = new StyleDictionary({
source: [
'node_modules/@hpe-web/design-tokens/src/primitive/primitives.json',
'node_modules/@hpe-web/design-tokens/src/semantic/color.light.json',
'node_modules/@hpe-web/design-tokens/src/semantic/dimension.xs-sm.json',
],
platforms: { /* your config */ },
});
sd.registerTransform(lineHeightUnitless); // px line-height → unitless ratio
sd.registerTransform(letterSpacingEm); // px letter-spacing → em
await sd.buildAllPlatforms();See src/hpe.resolver.json for the canonical token load order.
Locale metadata for custom pipelines:
import locales from '@hpe-web/design-tokens/src/locales.json' assert { type: 'json' };
// locales.de.coefficient.display === 0.75
// locales.ja.minFontSize === '14px'Package Contents
| Export | What |
|--------|------|
| @hpe-web/design-tokens/css/* | CSS custom properties (primary format) |
| @hpe-web/design-tokens/src/* | DTCG source + system metadata (breakpoints.json, locales.json, fonts.json) |
| @hpe-web/design-tokens/transforms | SD transforms + applyLocale utility |
License
Proprietary — Hewlett Packard Enterprise