@hashicorp/mds-tokens

Materia Design System (MDS) tokens and base styles.
This package provides the CSS custom properties, helper classes, and fonts that power HashiCorp’s web marketing design system.

Features

• 🎨 Design tokens as CSS custom properties (spacing, typography, primitive and semantic colors)
• 🔤 Fonts (HashiCorp Sans Variable, DejaVu Sans Mono)
• 📐 Custom Breakpoints for postcss configured apps
• 🧩 Base styles and helper classes for consistent UI

Installation

npm install @hashicorp/mds-tokens

Usage

Import base styles

You can import all tokens and base styles at once in your app's global stylesheet:

@import "@hashicorp/mds-tokens/style.css";

Or, in a JavaScript/TypeScript entry point:

import "@hashicorp/mds-tokens/style.css"

This will include:

• Global resets & normalization
• CSS variables for colors, typography, spacing, etc.
• Helper classes and font-face declarations

Fonts

HashiCorp Sans Variable and DejaVu Sans Mono are bundled:

@import "@hashicorp/mds-tokens/font/hashicorp-sans.css";
@import "@hashicorp/mds-tokens/font/dejavu.css";

Use CSS variables to access them:

body {
  font-family: var(--font-hashicorp-sans);
}

code {
  font-family: var(--font-dejavu-sans-mono);
}

[!NOTE] For Next.js projects, refer to the @hashicorp/mds-next README for guidance on integrating HashiCorp Sans and DejaVu Sans Mono using the Next.js font system.

File Exports

The package exports these entry points:

• @hashicorp/mds-tokens/style.css → Full tokens & base styles
• @hashicorp/mds-tokens/breakpoints.css → Responsive breakpoints
• @hashicorp/mds-tokens/font/* → Font CSS + font files

Development

Clone the repo, then:

# inside packages/mds-tokens
npm install
npm run build

Watch mode during development:

npm run dev

Build outputs:

• dist/style.css
• dist/breakpoints.css
• dist/font/*
• dist/index.js (shim that ensures CSS import)

Integration with PostCSS

This package is designed to work smoothly with PostCSS.
At minimum, enable postcss-import/postcss-url (or just postcss-preset-env with importFrom) so @import paths inside @hashicorp/mds-tokens resolve correctly.

Minimal example:

// postcss.config.js
module.exports = {
  plugins: {
    "postcss-import": {},
    "postcss-url": {},
    "postcss-preset-env": { stage: 3 }
  }
}

Custom media queries (breakpoints)

@hashicorp/mds-tokens publishes a breakpoints.css file that defines custom media queries via @custom-media. Loading these into PostCSS lets you write readable, tokenized media queries like @media (--medium-up) and have them compiled to standard min/max-width queries.

What’s provided

From @hashicorp/mds-tokens/src/custom-properties/breakpoints.css:

@custom-media --small (max-width: 767px);
@custom-media --small-up (min-width: 0px);
@custom-media --medium (min-width: 768px) and (max-width: 1119px);
@custom-media --medium-up (min-width: 768px);
@custom-media --large (min-width: 1120px);

Recommended PostCSS setup

Use @csstools/postcss-global-data to make the custom media definitions globally available (no need to @import them at the top of every file), and enable the custom-media-queries feature in postcss-preset-env so they’re transformed into standard media queries.

// postcss.config.js
const mdsBreakpointsCss = require.resolve("@hashicorp/mds-tokens/breakpoints.css")

/** @type {import('postcss-load-config').Config} */
module.exports = {
  plugins: [
    // Provide custom media globally (no per-file import needed)
    ["@csstools/postcss-global-data", { files: [mdsBreakpointsCss] }],
    "postcss-flexbugs-fixes",
    [
      "postcss-preset-env",
      {
        stage: 3,
        browsers: ["defaults"],
        autoprefixer: { flexbox: "no-2009" },
        features: {
          "nesting-rules": true,
          "custom-properties": false,
          "custom-media-queries": {
            preserve: false // compile to standard @media queries
          }
        },
        // Also acceptable way to load custom media for this plugin
        importFrom: mdsBreakpointsCss
      }
    ],
    ["postcss-normalize", { browsers: "defaults" }]
  ]
}

You can use either @csstools/postcss-global-data or importFrom to load the custom media. Using both is fine; global-data makes the definitions available to any plugin that can consume them, while importFrom is specifically read by postcss-preset-env.

Using the breakpoints in your CSS

.component {
  padding: 12px;
}

@media (--medium-up) {
  .component {
    padding: 16px;
  }
}

@media (--large) {
  .component {
    padding: 20px;
  }
}

With the config above, PostCSS compiles these to:

@media (min-width: 768px) { /* ... */ }
@media (min-width: 1120px) { /* ... */ }

Tips

• Keep preserve: false for custom-media-queries so you don’t ship @custom-media to the browser.
• If you author additional project-specific breakpoints, place them in a small file (e.g. src/styles/custom-media.css) and add it to both files: [...] in @csstools/postcss-global-data and importFrom in postcss-preset-env.
• The provided tokens are intentionally coarse (small / medium / large). Compose additional custom media on top if your product needs more nuanced tiers.

License

Copyright (c) HashiCorp, Inc.
SPDX-License-Identifier: MPL-2.0

See the LICENSE file for details.