[RFC] Refine @mui/system scope & responsibility

[siriwatknp]

Soon @mui/system will have 2 consumers (Material & Joy), so it is worth taking a step back and refining the scope of the system package to build the right architecture.

Scope & Responsibility

• System can be used to build any design system.
• System provides foundation theme properties that any design system must have. These properties cannot be renamed because they are bound with internal system functionality (shorthand & sx).
• System does not define the scale of each property. It is the design system choice (we might recommend using T-shirt sizes)

Theme properties

We believe that these are the foundation properties that are comprehensive to build a design system.

• shadow
• radius
• fontFamily
• fontSize
• fontWeight
• lineHeight
• letterSpacing
• palette: any related colors that will be used in different color schemes
• typography: built-in text styles for the design system

System forces the design system to use these properties but the scale (value of the property) can be any key-value pair.

For example:
Design system A can define the fontSize as small, medium, large
Design system B can define the fontSize as xs, sm, md, lg

System also provides build-in properties for handling systematic space, breakpoints, zIndexs.

• breakpoints: { keys, up, down, ...etc }
• spacing: fn
• zIndex: { ...list of generic components }

Typescript

interface Theme {
  palette: Palette; // only the palette that is not a scale
  fontFamily: Record<FontFamilyScale, string>;
  fontSize: Record<FontSizeScale, string | number>;
  fontWeight: Record<FontWeightScale, string | number>;
  lineHeight: Record<LineHeightScale, string | number>;
  letterSpacing: Record<LetterSpacingScale, string | number>;
  radius: Record<RadiusScale, string | number>;
  shadow: Record<ShadowScale, string>;
  typography: Record<TypographyScale, CSSObject>;
}

Note: All the properties are empty by default which means each property is an empty object in JS.

extending the theme via module augmentation

This example extends the typography to match the need

import { ThemeProvider, Box } from '@mui/system';

declare module "@mui/system" {
  interface TypographyScaleOverrides {
    body: true;
  }

  interface Palette {
    brand: {
      500: string;
    };
    text: string
  }
}

<ThemeProvider theme={{
  palette: {
    // ✅ typed-safe
    brand: { 500: '#ff5252' },
    text: '#121212',
  },
  typography: {
    // ✅ typed-safe
    body: {
      fontSize: '1rem',
    }
  }
}}>
  <Box sx={{ typography: 'body', color: 'brand.500' }}></Box>
</ThemeProvider>

Features

Component theming

System provides createStyled API to the consumer to create component that can connect to the theme:

import { createStyled } from '@mui/system';

const styled = createStyled({ defaultTheme: {...theme properties} }) // theme properties must follow system

const Button = styled('button', { name: 'TheButton', overridesResolver: (props, styles) => styles.root })({ ...styles });

theme.components can be used to configure & theme the specific component that renders inside the ThemeProvider:

import { ThemeProvider } from '@mui/system';

<ThemeProvider theme={{
  components: {
    // the name that registers in styled API
    TheButton: {
      defaultProps: { ... },
      styleOverrides: { ... },
      variants: [ ... ],
    }
  }
}}>
  <Button>Text</Button>
</ThemeProvider>

The sx prop

Every component created by styled API accept sx prop by default. The sx value can contain shorthand notation that connects to system theme properties:

const Button = styled('button')({ ...styles });

<Button sx={{
  p: 2, // will be transformed by theme.spacing
  color: 'primary.main' // will be transformed by theme.palette
}}>
  Text
</Button>

The stylesheet result is transformed based on the shorthand notation.

---

The current state

Material v5

Some of the nodes are not following the above-proposed structure:

• shadows is an array.
• fontSize, ...etc does not have a scale.
• shape.borderRadius is not a scale

If we agree on the proposed theme structure for the system (above), we can deprecate shadows shape and create an adapter & a codemod to ease the migration.

Joy

It already can start with the proposed theme structure on its own (no changes on the system) and stress test the experience to refine the final theme structure that will be a default for the System.

[siriwatknp]

The current state

Material v5

Some of the nodes are not following the above-proposed structure:

• shadows is an array.
• fontSize, ...etc does not have a scale.
• shape.borderRadius is not a scale

If we agree on the proposed theme structure for the system (above), we can deprecate shadows shape and create an adapter & a codemod to ease the migration.

Joy

It already can start with the proposed theme structure on its own (no changes on the system) and stress test the experience to refine the final theme structure that will be a default for the System.

[mnajdova]

Another breaking change for Material v5 is that the fontSize, fontFamily etc. are inside the typography key, which would need to change.