Documentation

UI Foundations Kit is a set of React components, layouts, and templates built on top of the MUI UI library (specifically @mui/material), that are pre-assembled and utilize a beautifully designed default theme.

Getting Started

A few quick requirements and set up steps are necessary to make use of the UI Kit's components.

Required Dependencies

The following libraries are used in UI Foundations Kit components:

@mui/material
@mui/x-data-grid (for the DataGrid component)
react-icons (for icons used throughout components)

All source code provided through this library depends on version 5 (or greater) of @mui libraries, which added support for theming with Emotion and the sx prop.

If you are coming from MUI v4 or earlier, you can use the codemods and migration guide provided by the MUI team to upgrade your project.

In addition to MUI, many examples rely on the popular react-icons package, which provides an assorted library of icons from open source icon packs. For you to be able to copy and paste the code without any problems, react-icons will need to be installed, or imports and uses of them will need to be replaced first.

Adding the theme

All components rely on the UI Foundations Kit theme, you can copy it from the Themes section of the UI library (with a Pro license) to add it into your own React app following these steps.

Copy the theme definition from the UI library
Create a new file in your project, e.g. ThemeProvider.tsx, or ThemeProvider.jsx if you aren't using TypeScript, and paste the entire contents of the theme definition into it

Import the <ThemeProvider> component that is exported automatically from your new ThemeProvider file and wrap your application with it (below is an example in a Next.js app)


jsx
// Next.js _app.js
import { ThemeProvider } from "./ThemeProvider"

function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider>
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

Now, you can copy and paste any of the examples and they should mirror their appearance from the UI Foundations Kit library

This is all you should need to get started, if you are interested in more differences in theme, or wish to customize it further, you can continue reading.

Theming

All components reference theme variables from the MUI theme, so that components can adopt to different themes with minimal effort. These values try to stick to default values similar to the ones provided by MUI, but can differ in some cases.

The philosophy for theming comes from principles described in the UI Foundations course, and is also based on principles of functional/utility CSS made famous by libraries like Basscss, Tachyons, Styled-System, and more recently, TailwindCSS.

Using the default theme

Components were designed with the default UI Foundations theme in mind. That means for best results, we recommend you utilize the provided theme, and extend it when needed.

To use the UI Foundations Kit theme, you need to copy the theme definition into your own project and wrap your app in the ThemeProvider component it exposes, as described in the Getting Started steps.

Using your own theme

If you'd like to bring your own theme, you may note some differences, which are documented in the differences section below.

You can merge an existing theme with the UI Foundations Kit theme by using the deepmerge function, which is exported from the @mui/utils component.

Differences from Material Design

UI Foundations Kit differentiates itself from the default Google Material design intentionally. The goal is to provide components with a more beautiful default style, while still supporting the entire API surface that MUI provides.

The following cases are described to explain why certain design choices were made that differ from the MUI recommendations and defaults. Some default theme definition properties (like default breakpoints) do not differ from the default theme.

Colors: color scales are defined in UI Foundations Kit as an array of tokens and overwrite the primary, secondary, warning fields, they are also exposed with names like blue, red, yellow, etc. so they can be used in a context of the intent of the component or used explicitly.


tsx
// using warning as a color
<Alert severity="warning">Yellow text</Alert>

// using an explicit color
<Typography color="yellow.700">Yellow text</Typography>

Typography: UI Foundations uses named typographic sizing values instead of names tied to HTML elements (like MUI) to encourage proper sizing of text on different elements.


tsx
// ❌ Material design
// typography: {
//   paragraph: "0.875rem",
//   body: "1rem",
//   h2: "1.25rem",
//   h1: "2rem",
// }
<Typography variant="paragraph">Small text</Typography>

// ✅ UI Foundations theme
// typography: {
//   xs: "0.75rem",
//   sm: "0.875rem",
//   md: "1rem",
//   lg: "1.125rem",
// }
<Typography size="sm">Small text</Typography>

Shadows: UI Foundations Kit uses a different set of shadows than MUI, which are more subtle and less aggressive. They are defined as an array the same as default MUI, but lack as many elevation values. MUI has 25 elevation values, UI Foundations Kit has only 6.
Transitions: Instead of longer transition speeds, UI Foundations Kit favors shorter transition speeds to make the UI feel more responsive.
Inputs: For greater control over the visual appearance of inputs, UI Foundations Kit prefers the composition of components like FilledInput and FormControl over the higher level abstractions like TextField.

Fonts (optional)

All examples use the Inter font, which was designed for use in building UIs and is 100% open source. It can also be used as a variable font and looks great in different weights and contexts.

To add Inter to your site, you can install it with a link tag like this:


html
<!-- from Rasums Andersson's site -->
<link rel="stylesheet" href="https://rsms.me/inter/inter.css" />

<!-- from Google fonts -->
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css?family=Inter:300,400,500,600,700,800"
/>

You can substitute Inter for other fonts if you like, though all components were built with it as the primary font in mind.

Automated dynamic line height

Line height (sometimes called tracking) has suggested values for different font sizes via a formula on the Inter website. This formula is applied to any MuiTypography component that has a fontSize prop passed into it. You can remove this behavior by deleting the theme modifications to MuiTypography in the ThemeProvider.