npm package: @hpe-web/design-tokens
Description: HPE Design System — design tokens (CSS, JSON)
Latest version: 1.2.1

# @hpe-web/design-tokens

HPE Design System design tokens — CSS custom properties, DTCG source, locale overrides, and utilities.

## What's new in v1.2.0

**CSS consumers: no changes required.** If you use the DTCG source or static metadata via package imports, see the migration notes below.

- Token source restructured: `dtcg/` + `static/` replaced by `src/` with consolidated semantic files
- `@hpe-web/design-tokens/dtcg/*` and `@hpe-web/design-tokens/static/*` exports removed — use `@hpe-web/design-tokens/src/*`
- `sm-xs` → `xs-sm` breakpoint rename in `src/breakpoints.json` and source file paths
- `src/component/button.json` added — button component tokens
- Token values updated (`color.light`, `color.dark`, `button`) from Supernova sync

[Full changelog →](CHANGELOG.md)

[Full changelog →](https://github.com/HPE-EMU/design-system/blob/main/packages/tokens/CHANGELOG.md)

---

## Install

```bash
npm install @hpe-web/design-tokens
```

## Usage

### CSS (recommended)

Load the base file and any overrides your app needs. The cascade handles viewport, theme, and locale simultaneously.

```html
<!-- 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:

```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:**
```html
<body data-theme="dark">…</body>
```

**Locale switching:**
```html
<html lang="de">…</html>
```

### Static metadata

All three metadata files live in `static/`:

```js
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:

```js
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:

```js
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