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

• _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/*.scss - Uses Sass maps to export global tokens as CSS variables for external use.
• contextual-variables/*.scss - Uses Sass maps to generate contextual token CSS variables for use across components and applications.
• 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.
• fonts.scss - Collection of font styles for loading fonts - compiles separately from other scss files.

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 transpile the SCSS and get the CSS files, run:

npm run build:styles

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';