@muraldevkit/ds-foundation
v2.13.0
Published
Mural's design system's Foundation package containing our design language features used across all components
Downloads
1,914
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
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 exceptfonts.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:
@muraldevkit/ds-foundation/dist/foundation.css
@muraldevkit/ds-foundation/dist/foundation.min.css
@muraldevkit/ds-foundation/dist/fonts.css
@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';