# @muraldevkit/ds-foundation

> Mural's design system's Foundation package containing our design language features used across all components

Latest version **2.29.0** (published 2026-08-04) · https://www.mural.co/terms/developer-addendum license · 0 weekly downloads

## Install

```sh
npm install @muraldevkit/ds-foundation
pnpm add @muraldevkit/ds-foundation
yarn add @muraldevkit/ds-foundation
bun add @muraldevkit/ds-foundation
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.29.0 |
| Published | 2026-08-04 |
| First published | 2023-03-24 |
| Weekly downloads | 0 |
| License | https://www.mural.co/terms/developer-addendum |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 482.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | muralco, mural-devvel |

## Links

- npm: https://www.npmjs.com/package/@muraldevkit/ds-foundation
- npm.io page: https://npm.io/package/@muraldevkit/ds-foundation

## Recent versions

- 2.29.0 (latest) — 2026-08-04
- 2.28.1-dev-eNqR.1 (dev) — 2026-07-31
- 2.28.1 — 2026-07-30
- 2.28.0 — 2026-07-23
- 2.27.0 — 2026-07-20
- 2.26.0 — 2026-07-17
- 2.25.0 — 2026-07-14
- 2.24.0 — 2026-07-14
- 2.23.0 — 2026-07-06
- 2.22.0 — 2026-06-22
- 2.21.0 — 2026-06-19
- 2.20.0 — 2026-06-18
- 2.19.0 — 2026-06-01
- 2.19.0-dev-rMoq.1 — 2026-05-29
- 2.18.0 — 2026-05-18
- … 42 more at https://npm.io/package/@muraldevkit/ds-foundation/versions

## README

# Foundation package overview

This package contains the design language foundations of Mural's design system.
It includes design tokens, global styles, and utilities.

## Table of contents

1. [Design tokens](#design-tokens)
   1. [Token reference](#token-reference)
1. [Installation](#installation)
   1. [Global styles and utilities](#global-styles-and-utilities)
      1. [Noteworthy files](#noteworthy-files)
1. [Usage](#usage)
   1. [Importing Foundation styles](#importing-foundation-styles)
      1. [SCSS imports](#scss-imports)
         1. [Available Sass mixins](#available-sass-mixins)
         1. [Available Sass functions](#available-sass-functions)
      1. [CSS files](#css-files)
         1. [Available utility classes](#available-utility-classes)
      1. [Important notice about fonts](#important-notice-about-fonts)

### Design Tokens

Tokens are authored as [DTCG](https://tr.designtokens.org/format/)-format JSON under `src/tokens/` and compiled by [Style Dictionary](https://styledictionary.com) into the CSS custom properties (`--mrl-*`) this package ships. Please read our internal design token guides to understand their architecture (global, contextual vs. component hierarchy) and adoption guides, and [`architecture.md`](./architecture.md) for how the pipeline works. Please follow the [contribution](./docs/contributing.md) best practices when adding or updating tokens.

#### Token reference

**`dist/TOKENS.md` is the reference for every token in the design system** — one table per family, split into global and contextual tiers, listing each token's CSS custom property name, the value as it lands in real CSS, the resolved value behind an alias, the hex equivalent for colors, and its description. It opens with the usage rules that are easy to get wrong (colors are RGB triplets and must be wrapped; some values change at the 600px breakpoint) and with guidance for finding a token from an intent or from a raw hex/px value you want to replace.

It is generated from `src/tokens/**/*.json` on every build, so it can never be out of date with the tokens it documents. Read it at:

```
node_modules/@muraldevkit/ds-foundation/dist/TOKENS.md
```

If you are working in this repo, run `npm run build` in `packages/foundation` first — `dist/` is gitignored, so the file exists only after a build. Do not edit it; edit the JSON sources and rebuild.

### Installation

Review the design system's global usage guidelines to learn how to install individual design system packages. This package's name is `@muraldevkit/ds-foundation`.

#### Global styles and utilities

Under `src/styles` you'll find the foundation styles of the design system that are either applied globally to an application or shared across many components. We use [SCSS](https://sass-lang.com) as the CSS preprocessor.

#### Noteworthy files

- **\_tokens.scss** — **Generated by Style Dictionary** from `src/tokens/**/*.json` during `npm run build`. Declares every `--mrl-*` custom property at `:root`. Committed to the repo as a verified snapshot of what the JSON compiles to. **Do not edit by hand** — edit the JSON sources instead.
- **\_functions.scss** - Helper and utility functions used to reduce repetitive code.
- **\_mixins.scss** - Helper and utility mixins used for reducing repetitive code when the output is CSS.
- **global-variables/breakpoints.scss** — Sass-only breakpoint variables (`$mrl-breakpoint-01..05`). Lives outside the JSON because `@media` queries cannot reference `var(--…)`.
- **contextual-variables/\*.scss** — Viewport-responsive overrides on top of the JSON-sourced custom properties. Used for the small set of tokens whose value changes inside `@media` blocks (Style Dictionary emits a flat `:root {}` and cannot model media queries).
- **baseline.scss** - Ensures modern, cross-browser element rendering. Based off of [Normalize.css](https://necolas.github.io/normalize.css/).
- **index.scss** - Collection of all SCSS modules in the `styles` directory **except** `fonts.scss`. Forwards `_tokens` first.
- **fonts.scss** - Collection of font styles for loading fonts - compiles separately from other scss files.

The authored source of truth for every token is the DTCG-format JSON under `src/tokens/global-variables/` and `src/tokens/contextual-variables/`. See [`architecture.md`](./architecture.md) for the full pipeline.

Applications are encouraged to use these files in their custom implementations to assist with alignment and consistency as Mural's UI design updates.

## Usage

### Importing Foundation styles

#### SCSS imports

If you are using Sass or SCSS in your project, you can import our `*.scss` files from the package into your files.

```scss
@use '~@muraldevkit/ds-foundation/src/styles/index';
```

Alternatively, you can import the files into whatever build tool or bundler you're already using or directly use the [CSS files](#css-files).

##### Available Sass mixins

To support the reuse of styles across components, the design system provides [multiple mixins](./docs/mixins.md). You can also use these within products as a way to maintain consistency. We provide these mixins so you can apply these styles inline with your other styling and then leverage the web server's capabilities of combining these duplicate styles to reduce bloat. If you're running into performance issues, you can use our [utility classes instead](#available-utility-classes).

##### Available Sass functions

To support the a more developer friendly environment, the design system provides [multiple functions](./docs/functions.md). You can also use these within products for easier implementation and retain consistency.

#### CSS files

To compile the DTCG token JSON into `_tokens.scss` and then transpile the SCSS to CSS, run:

```bash
npm run build
```

This runs `build.mjs`, which (1) executes Style Dictionary to regenerate `src/styles/_tokens.scss`, `zeroheight/tokens.json`, and `dist/TOKENS.md` from `src/tokens/**/*.json` and (2) compiles the Sass entry points to expanded + minified CSS with source maps. The DTCG JSON is also copied to `dist/tokens/` for downstream tooling.

The design system provides compiled and minified versions of the baseline foundation styles and font declarations. The available CSS files are:

1. `@muraldevkit/ds-foundation/dist/foundation.css`
1. `@muraldevkit/ds-foundation/dist/foundation.min.css`
1. `@muraldevkit/ds-foundation/dist/fonts.css`
1. `@muraldevkit/ds-foundation/dist/fonts.min.css`

The published package also contains two non-CSS outputs:

1. `@muraldevkit/ds-foundation/dist/TOKENS.md` — the generated [token reference](#token-reference).
1. `@muraldevkit/ds-foundation/dist/tokens/**/*.json` — the DTCG token sources, for tooling that reads tokens as structured data.

##### Available utility classes

To support the reuse of styles across components, the design system provides [multiple utility classes](./docs/css-utilities.md). You can also use these within products as a way to maintain consistency and provide easier implementation of theming.

#### Important notice about fonts

Please be aware that if you decide to use our font declarations, you need to copy the typeface files out of our package. They are located at `@muraldevkit/ds-foundation/assets/fonts`. If you are using our compiled font declarations, the copied files need to be located in a directory called `assets/fonts` which is a sibling of the CSS directory.

For example, if your CSS file is at `/project/styles/fonts.css` then the typeface files need to be at `/project/assets/fonts`.

Alternatively, you can import our `fonts.scss` file and set a custom font directory path using our global SCSS variable:

```scss
$mrl-font-dir: '/local/path/to/font/files';
@import '../../node_modules/@muraldevkit/ds-foundation/src/styles/fonts';
```

---
_Source: https://npm.io/package/@muraldevkit/ds-foundation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._