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
2. Installation
   1. Global styles and utilities
      1. Noteworthy files
      2. Sass maps
3. Usage
   1. Importing Foundation styles
      1. SCSS imports
         1. Available Sass mixins
         2. Available Sass functions
      2. CSS files
         1. Available utility classes
      3. Important notice about fonts

Design Tokens

Please read our internal design token guides to understand their architecture (global, contextual vs. component hierarchy) and adoption guides. Please follow the contribution best practices when adding or updating tokens.

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 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.
• grid.scss - Utility classes to allow applications to create consistent layouts.
• 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 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.

@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.

Available Sass mixins

To support the reuse of styles across components, the design system provides multiple mixins. 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 Sass functions

To support the a more developer friendly environment, the design system provides multiple functions. 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:

npm run build

This runs build.mjs, which (1) executes Style Dictionary to regenerate src/styles/_tokens.scss 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
2. @muraldevkit/ds-foundation/dist/foundation.min.css
3. @muraldevkit/ds-foundation/dist/fonts.css
4. @muraldevkit/ds-foundation/dist/fonts.min.css

Available utility classes

To support the reuse of styles across components, the design system provides multiple utility classes. 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:

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