mpulse-design-system

mpulse-design-system is a collection of reusable React components and theming tools designed to provide a consistent user interface across mPulse applications. It leverages MUI v7 for its foundation and extends it with custom styles, components, and utilities tailored to the mPulse brand.

Installation

npm:

npm install mpulse-design-system

yarn:

yarn add mpulse-design-system

Getting Started

Most components are thin re-exports of MUI, and everything that makes them look like mPulse lives in the theme. Wrap your app in ThemeProvider once, at the root — without it, components fall back to MUI's default appearance.

import * as React from 'react';
import { createRoot } from 'react-dom/client';
import { Button, ThemeProvider, theme } from 'mpulse-design-system';

function App() {
  return <Button variant="contained">Hello World</Button>;
}

createRoot(document.getElementById('root')).render(
  <ThemeProvider theme={theme}>
    <App />
  </ThemeProvider>,
);

Fonts

The theme sets Roboto, Helvetica, Arial, sans-serif. The design system does not bundle the webfont — apps load it, which is MUI's own guidance. Without this step the rendered face is whatever happens to be installed on each viewer's machine:

npm install @fontsource/roboto

// once, at the app entry point — the theme uses weights 300, 400, 500 and 700
import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/700.css';

Theming and branding

To layer app- or client-specific branding on top, pass the mPulse theme as the base to MUI's createTheme. The palette keys are semantic roles, so overriding primary reshapes every component that references it:

import { createTheme } from '@mui/material/styles';
import { theme } from 'mpulse-design-system';

const brandedTheme = createTheme(theme, {
  palette: { primary: { main: '#0079AD' } },
});

Most component overrides in the theme are MUI style callbacks (({ theme }) => …), so they follow the branded palette. MUI's createTheme replaces a callback slot when the branding supplies an object for that same slot; to extend one, give the slot as a callback.

This is the supported way to re-brand. Prefer it over overriding component styles in the app.

Components

Browse the complete component library in our Storybook.

Documentation

For component APIs, refer to MUI's documentation — props and behavior are MUI's.

Appearance is not. src/theme/index.ts overrides MUI's defaults for roughly 28 components, so where MUI's docs describe a default style, this theme is authoritative. Palette, typography, breakpoints and shadows live alongside it in src/theme/.

Changelog

Check the changelog for release notes and version updates.

Contributing

PRs target develop. npm test, npm run lint, npm run typecheck and npm run prettier:check run on every pull request, along with a Storybook job that renders every story in Chromium and fails if any of them throw.

Working locally:

npm install
npm run storybook        # component workbench on :6006
npm test                 # unit tests
npm run test:storybook   # story smoke tests, needs storybook running

Add a story for any new component — Storybook is the reference other teams read.

License

MIT © mpulsemobile