DEV Community: Quintin Maseyk

Unity & React

Quintin Maseyk — Mon, 03 Jul 2023 12:18:16 +0000

Unity is a powerful and versatile platform for 3D development. It is known for its ability to handle complex 3D models and environments, as well as its strong focus on creating visually appealing and interactive experiences. Unity also has a strong community and a wealth of documentation and resources available online.

ReactJS is a popular choice for building user interfaces because it's easy to learn and use. It's also very flexible and can be used to build a wide range of applications, from simple websites to complex web apps. It has a wide range of support and it's index in the State of Frontend report is strong.

The reason you'd consider using React with Unity is because React is a great choice for building user interfaces, but it's not so great for building 3D models and environments. Unity is a great choice for building 3D models and environments, but it's not so great for building user interfaces. So, by joining forces, we can create a powerful combination that allows us to build both 3D models and user interfaces.

Table of Contents:

Web View
Layered Architecture
- Layer 1: Unity Application
- Layer 2: Web View
- Layer 3: React Application
- Bringing it all together
- Lifecycle of Events
JS API Perspectives
- Unity Perspective
- React Perspective
Conclusion

Web View

Unity is a popular platform for building games and interactive experiences, but it also has many features that make it an ideal choice for other types of applications. One such feature is Web View, which allows you to display web content within your Unity application.

Web View can be used to create dynamic user interfaces that can be updated in real-time. For example, if you have a news app built with Unity, you could use Web View to display the latest headlines from your website or blog. This would allow users to stay up-to-date on the latest news without having to leave the app.

Another benefit of using Web View is that it allows you to easily integrate web-based functionality into your Unity project. If there's a particular API or service that you need access to in order to build your application, you can simply use Web View to embed that functionality directly into your project.

Web View works by creating a new view within your Unity application where web content can be displayed. You can control this view just like any other element in your scene by adjusting its position and size or adding animations and special effects.

Layered Architecture

The layered architecture pattern is a software design pattern that divides the system into layers. Each layer has a specific responsibility and interacts with the layers above and below it. The layers are typically organized in a hierarchical fashion, with the highest layer being the user interface layer and the lowest layer being the data/hardware accelerator layer.

Layer 1: Unity Application

The Unity Application is the bottom layer of the architecture. It's responsible for all of the 3D rendering capability. The Unity application communicates with the other layers through a set of interfaces, which are defined in the Unity application layer.

This layer deploys Web View where it should expand across the entire screen. It'll receive events from the React application and update the scene accordingly.

Layer 2: Web View

The Web View layer is responsible for rendering the web content (React application). Since Web View imeplements the Chromium engine it can render any web content. This layer sits inbetween Unity and React and initialises the React application.

Web View should be implemented to be responsive and stetch the full size of the application's viewport. From Unity's perspective, Web View's z-index should be the topmost so that so React can be rendered on top of the Unity application.

Since it's a Chromium implementation, things like the global window object is available to the React application. This means that the React application can communicate with the Unity application through the window object (more on this will follow).

Layer 3: React Application

The React application is the top layer of the architecture. It contains all of the business logic and all of the user's external API access patterns, such as: authentication, fetching contextual menu information, user selections etc. It's also responsible for rendering the user interface. It'll receive events from Unity and update the UI accordingly. Likewise, it'll send events to Unity to update the scene.

Bringing it all together

High level view

What it looks like in reality

Lifecycle of Events

Unity is loaded
Unity initialises Web View
Web View loads React
React initialises
React sets up vuplex event handlers
React sends onLoad event to Unity
Unity receives onLoad event from React
Unity sends 3dModelLoaded event to React
React receives 3dModelLoaded event from Unity ...
User interacts with React, sending events to Unity
Unity receives events from React and updates the scene accordingly; and so on.

JS API Perspectives

The JS API is a set of interfaces that allow the Unity to communicate with the React and vice-versa.

Unity Perspective

From a Unity perspective, the JS API is a set of interfaces that allow Unity to communicate with React and vice-versa. The JS API is implemented as a set of C# classes that are exposed to the Unity application through a set of interfaces. These interfaces define the methods that can be called by the Unity application and the events that can be sent to the React application.

The Unity layer is responsible for implementing the JS API with a set of predefined events. Each event has a command and optional payload. The command is a string that identifies the event type. The payload is an object that contains additional information about the event.

An example of Unity sending an event to React would look like:

{
  command: '3dModelLoaded',
  payload: {
    name: 'PerthCity',
    radius: 1000
  }
}

An example of Unity receiving an event from React would look like:

{
  command: 'onLoad',
  payload: {
    version: '1.0.0',
    state: 'ready'
  }
}

Notice how both are being represented as JSON objects. This is because the JS API is designed to be used with JSON. This makes it easy for developers to work with the JS API since they don't have to worry about converting data types or serializing/deserializing objects (custom data types still need to be catered for during deserialization of JSON -> Unity).

React Perspective

Like Unity's implementation, React also needs to implement its own event handlers to be able to both send and receive events to and from Unity. Web View suggest to implement vuplex on the window scope. Vuplex is a JS API bridge that allows Unity and React to communicate with each other.

3D WebView has a built-in window.vuplex.postMessage() JavaScript API that you can use to send messages from JavaScript to C#. Since it's built into the browser, you don't need to include any 3rd party scripts in the page in order to utilize it. The following example illustrates how to use this JavaScript API in a page script or in a script executed via ExecuteJavaScript():

Learn more

Following the Unity example of sending an event to let Unity know the React app has initialised, it'll look like something like this:

const handleOnLoad = () => {
  window.vuplex.postMessage('onLoad', {
    version: '1.0.0',
    state: 'ready'
  });
}

Notice that the window.vuplex object is used to send the message. This is the same object that Unity uses to send messages to React. This means that both Unity and React can communicate with each other through the window.vuplex object (aka JS API bridge).

An example of receiving an event from Unity would be:

window.vuplex.onMessage((event) => {
  switch (event.command) {
    case "3dModelLoaded":
      console.log(event.payload);
      break;
    default:
      break;
  }
});

The onMessage method takes a callback function as an argument. This callback function will be called whenever an event is sent from Unity. The event object contains information about the event such as the command and payload. It's up to the developer to decide what to do with this information.

Conclusion

Splitting the application into layers allows us to separate concerns and make it easier to maintain and extend the application in the future. It also makes it easier to test each layer individually, which can be useful when debugging issues or adding new features.

The release cycle of the application is also improved because each layer can be released independently. This means that if there's a bug in one layer, it can be fixed without having to release the entire application.

If you're interested in learning more about how we can help with your project, please get in touch!

Why Skeleton Loaders Are The Better Option

Quintin Maseyk — Wed, 13 Jul 2022 04:21:59 +0000

Since ajax was introduced we've been familiar with circular loading spinners, dot-dot-dot animations, crazy logo transitions and more, all in place to distract the user while the application requests more data to present back.

Loading indicators are typically displayed when a page/component mounts or when a user interacts with the application (ie. submitting a form, searching for something, etc). These are essential to the overall user experience of an application as it visually lets the user know something is happening.

⚠️ This blog post is staged around Client-Side Rendering (CSR) where static pages mount components which in turn fetch dynamic content during the page load cycle. It is not intended for you to replace all other loading indicators.

What's the problem?
- Problematic Examples
How Skeleton Loaders Can Help
Conclusion

What's the problem?

The problem with circular loaders is they don't set the scene or express well enough on how the content will be rendered in the UI once it has finished loading.

A few problems can arise from this but I'd like to focus on the following:

The user has to analyse and discover the revealed content, inevitably increasing the user's cognitive load.
Cumulative Layout Shift (CLS).

Problematic Examples

Circular Loader with no appropriate dimension

The following gif animation shows 1 Credit Card box using the circular loading indicator; once the content is ready the loading indicator immediately gets removed and the true Credit Card box's content gets revealed. You'll notice this pushed the below content down, hence the degradation to our CLS score.

💡 Why CLS matters:

Have you ever been to a site on either a desktop or mobile phone, got presented with some content, found a link to click on but just as you did the link jumped away from you? Worse yet, you ended up clicking something else completely irrelevant! This is occuring more often than none and the experience is frustrating! This is why performance tools like Lighthouse are increasing their weight (penalty) of CLS more and more.

Circular Loader with an appropriate dimension

This is the same implementation as the above with the addition of the developer ensuring the circular loading indicator fills out to the default size of a rendered Credit Card box.

This is starting to feel a bit better but I'm having to cognitively re-read everything in the box to make my next move.

How Skeleton Loaders Can Help

Skeleton loaders force the developer to think about the content which it is emulating in a much more heuristic manner as they would have to take some time to think about the content's:

box model: position, height, width, padding...
content layout: rows, columns, flex direction, justify content...

Let's use the following screenshot as our example.

Our task is to create a skeleton for the "Credit Card Summary" cards. The goal is to style the skeleton close enough to the design so there are no surprises when the content renders.

I will be using MUI's Skeleton component to construct our new <CreditCardSkeleton> component. MUI's Skeleton component expose 3 variants: Text, Circular, Rectangle.

Like most things when developing from a design it's best to develop from the outside in. I tend to follow these steps in my head:

1: Figure out the root node's layout constraints. Ask yourself what direction the content flows, does the content wrap, what spacing is between each item?

2: Figure out the content type. Is it a card, body text, table, video, image?

3: Figure out the inner content layout. In our case there are 3 rows 2 columns

Rows

Columns

4: What are the key landmarks for the inner content? You decide how simple or complex your skeleton should be

Simple

Complex

We now have enough information to construct our skeleton and here's what we should end up with:

A few things to note:

I chose to implement complex landmarkings as it better transitioned when the true content was revealed.
A second skeleton in the horizontal list was added to let the user know there may be more than one Card after the loading finishes.
Consecutive skeletons have their opacity lowered to emphasise there may/may-not be more than one card after the load has completed.

Conclusion

When skeletons are implemented correctly you'll not only make your application look and feel better, but deliver a more intuitive experience to your users as they will now have a better understanding of page layouts and content landmarks before the true content has even loaded.

Don't be shy, get in touch with us!

FED Talk! Episode 3: Setting Up Routes in React

Quintin Maseyk — Fri, 11 Jun 2021 07:00:20 +0000

In today's episode we will step through how to implement your applications routing using React Router, configuring everything from:

Defining Routes,
Linking between content,
Setting up parameters,
Utilizing Route hooks

Let's get started!

Table of Contents:

🤔 What's a Route?
Setting Up Routing in React
Configuring Routes
Linking between pages
Parameterized Routes
Route Hooks
useHistory vs useLocation
Redirect
🙏 Closing

🤔 What's a Route?

From the get-go React Apps are configured as a Single Page Application (SPA).
This means when you build your App everything is shelled into your projects root index.html file made available in the public folder. If you create anchor tag links expecting your users to be navigated to another landing URL, it simply will not work as the only .html page exported from the build at this stage is the root file.
This is where the recommended library React Router comes into play.

A route is where we bind the URL to our React App and as developers, we can configure them in a meaningful way.
For example we can configure:

our home page: /,
nested child pages: /product-category/products,
contextual information: /product-category/products/ABC -> /product-category/products/:productId -> console.log(productId) // "ABC",
redirects,
fallbacks to things like a "Page not found" page.

Setting Up Routing in React

Before we start implementing we should spend some time upfront to design what our Routes will look like.
The following questions help me during this phase:

Will your App be publicly available and are you expecting Google (or any other engine) to index your pages?
The following topics are worth a read:

Will users copy/paste URLs to deep link into your content?

Will users bookmark URLs for future use?

For the rest of our journey we will build out our App answering the last two questions.

Let's check the current state of our App to see how we can design our Information Architecture.

There are 3 areas which can be broken down into smaller digestible bits of content: Typographies, Colour Palette, Buttons. Off the bat we can declare 3 routes:

/typographies
/colour-palette
/buttons

Take some time to imagine how your App will evolve. I foresee it containing a mixture of information:

Getting Started (Home page): /
UI: /ui/*
Components: /components/*
Feedback: /feedback
Page Not found

So, because of this we should change our routes to be:

/ui/typographies
/ui/colour-palette
/ui/buttons

Now that we have a clear idea on how our routes can be implemented, lets install the react-router-dom library to get started:

npm install react-router-dom
npm install --save-dev @types/react-router-dom

Configuring Routes

It's best to setup Routes at the highest logical level in your App so all the Router contextual information can propagate down to your components.

Following on from the previous episode, we can update our App code with the following:

// src/App.tsx

import { BrowserRouter } from "react-router-dom";

import { CssBaseline, ThemeProvider } from "@material-ui/core";

import AppBar from "./components/AppBar";
import BodyContent from "./components/BodyContent";
import Routes from "./Routes";
import Theme from "./theme";

export default function App() {
  return (
    <ThemeProvider theme={Theme}>
      <CssBaseline />
      <BrowserRouter>
        <AppBar />
        <BodyContent>
          <Routes />
        </BodyContent>
      </BrowserRouter>
    </ThemeProvider>
  );
}

Note how the BrowserRouter component wraps your content.

Update the BodyContent code with the following:

// src/components/BodyContent/index.tsx

import React from "react";

import { makeStyles } from "@material-ui/core";

const useStyles = makeStyles(() => ({
  root: {
    margin: '0 auto',
    maxWidth: '57rem',
    padding: '2rem 0'
  }
}))

export default function BodyContent({ children }: { children: React.ReactNode }) {
  const classes = useStyles();

  return (
    <main className={classes.root}>
      {children}
    </main>
  )
}

Note how we've replaced the manually imported UI components with React's Children prop; this is where our new Router will pass in the Component per the browser's URL.

Lastly we've got to create our Routes file:

// src/Routes.tsx

import React from "react";
import { Route, Switch } from "react-router-dom";

import Buttons from "./ui/Buttons";
import ColourPalette from "./ui/ColourPalette";
import Typographies from "./ui/Typographies";

export default function Routes() {
  return (
    <Switch>
      <Route path="/ui/buttons" component={Buttons} />
      <Route path="/ui/colour-palette" component={ColourPalette} />
      <Route path="/ui/typographies" component={Typographies} />
    </Switch>
  );
}

Note the use of Route and Switch.

React Router: Route

The Route component is perhaps the most important component in React Router to understand and learn to use well. Its most basic responsibility is to render some UI when its path matches the current URL.

Learn more

React Router: Switch

Renders the first child <Route> or <Redirect> that matches the location.
How is this different than just using a bunch of <Route>s?
<Switch> is unique in that it renders a route exclusively. In contrast, every <Route> that matches the location renders inclusively.

Learn more

Let's take a look at what our Buttons page looks like, by typing in the URL: "http://localhost:3000/ui/buttons"

❤️
That's pretty cool, we've now just split out the content for our App!

Linking between pages

Now that our base routes have been setup, let's configure the Links in our left menu to allow users to navigate between the content.

// src/components/MainMenu/index.tsx

import React from "react";
import { useHistory } from "react-router";

import { Drawer, List, ListItem, ListItemText } from "@material-ui/core";

const menuItems = [
  { label: 'Buttons', url: '/ui/buttons' },
  { label: 'Colour Palette', url: '/ui/colour-palette' },
  { label: 'Typogaphies', url: '/ui/typographies' },
]

function MenuItems({ setOpenMenu }: { setOpenMenu: React.Dispatch<React.SetStateAction<boolean>> }) {
  const { push } = useHistory();

  const onLinkNavigation = (url: string) => {
    push(url);
    setOpenMenu(false);
  }

  return (
    <List>
      {menuItems.map(({ label, url }) => (
        <ListItem button key={label} onClick={() => onLinkNavigation(url)}>
          <ListItemText primary={label} />
        </ListItem>
      ))}
    </List>
  )
}

/* ...Rest of code */

Notes:

We moved the menuItems outside the component, this is simply to initialize the menuItems once and refer to it there after.
We declare the use of the History hook and explicitly require its push function for future use.
We then created a function onLinkNavigation to manage the users click event. Upon clicking we instruct the App to push the new navigation URL into the browsers History queue; then we hide the menu.

Here's what this new change looks like:

⚠️
Hang on, this implementation has flaws!

Even though this functionally works, it's unfortunately not accessible!
MUI Have realized this is a problem and have provided a way for us to integrate 3rd party components such as react-router-dom Link component; which would ultimately render our ListItem component as an anchor tag, with a href value.

Let's make the changes:

// src/components/MainMenu/index.tsx

import React from "react";
import { Link } from "react-router-dom";

import { Drawer, List, ListItem, ListItemText } from "@material-ui/core";

const menuItems = [
  { label: 'Buttons', url: '/ui/buttons' },
  { label: 'Colour Palette', url: '/ui/colour-palette' },
  { label: 'Typogaphies', url: '/ui/typographies' },
]

function MenuItems({ setOpenMenu }: { setOpenMenu: React.Dispatch<React.SetStateAction<boolean>> }) {
  return (
    <List>
      {menuItems.map(({ label, url }) => (
        <ListItem
          button
          component={Link}
          key={label}
          onClick={() => setOpenMenu(false)}
          to={url}
        >
          <ListItemText primary={label} />
        </ListItem>
      ))}
    </List>
  )
}

/* ...Rest of code */

Notes:

We've imported the Link component from react-router-dom and then passed it through to the ListItem "component" property. This then extends the TypeScript definition of ListItem with the types of Link, making the "to" property available.
We then removed the need to include the History hooks as we've passed the menuItem's url value into the "to" property.
We update the "onClick" property to collapse the main menu there after.

🍾
Those links are now accessible!

Parameterized Routes

Depending on your App's architecture and the data in which it needs to process, there will be a time where you need to configure parameters.

There are two type of parameters:

Path Parameters:

/productCategory/:category/product/:productId

const { match: { params }} = useParams();
console.log(params);
// { category: string?, productId: string? }

const { search } = useLocation();
console.log(search);
// ""

Search Parameters:

/products-page?category=CATEGORY_ID&productId=PRODUCT_ID

const { search } = useLocation();
console.log(search);
// "?category=CATEGORY_ID&productId=PRODUCT_ID"

const { match: { params }} = useParams();
console.log(params);
// {}

You can also combine the two:

/productCategory/:category/product/:productId?tab=general

const { match: { params }} = useParams();
console.log(params);
// { category: string?, productId: string? }

const { search } = useLocation();
console.log(search);
// "?tab=general"

It can be hard to differentiate when to use either solution but I draw the line applying the following principles:

Use Path params if it follows on the Information Architecture, maintaining its hierarchy.
Fallback to Search params if it breaks the above or the Search param is used to alter a smaller section of your App.

For pure example, we can implement Parameterized Routes in our UI Library (this is just for demonstration purposes).

import React from "react";
import { Route, RouteComponentProps, Switch } from "react-router-dom";

export default function Routes() {
  return (
    <Switch>
      <Route path="/ui/:name" component={UIPage} />
    </Switch>
  );
}

function UIPage({ match: { params: { name } } }: RouteComponentProps<{ name?: string }>) {
  return (
    <>
      name: {name}
    </>
  )
}

Notes:

We've replaced all of the explicit routes with a single pattern match Route. The convention is to add your arbitrarily defined parameter name after the parent route. ie. /ui/ = parent route. :name = parameter name.
We've then created a UIPage component so you can see how the parent Route component propagates data down.
We've defined the parameter Type inside the RouteComponentProps definition so our codebase has reference to it.

Here's a screenshot illustrating how the URL affects the View and what props get passed down through the Route HoC.

Route Hooks

There will be times you'll need access to the URL parameter when you are many levels deep in the component tree.
This is where Route Hooks come into play, the hook exposes the current state of your BrowserRouter.

Here's an example demonstrating the above need:

import React from "react";
import { Route, RouteComponentProps, Switch, useRouteMatch } from "react-router-dom";

export default function Routes() {
  return (
    <Switch>
      <Route path="/ui/:name" component={UIPage} />
    </Switch>
  );
}

function UIPage({ match: { params: { name } } }: RouteComponentProps<{ name?: string }>) {
  return (
    <>
      name: {name}
      <Child1 />
    </>
  )
}

function Child1() {
  return <Child2 />
}

function Child2() {
  return <Child3 />
}

function Child3() {
  const { params } = useRouteMatch();
  return (
    <>
      <br />
      URL parameter: {JSON.stringify(params)}
    </>
  )
}

Notes:

The parent page renders Child1 -> renders Child2 -> renders Child3
Child3 uses the the useRouteMatch hook which exposes the route's current Match properties. The component now has access to the URL parameter to do as it wishes.

Notice how clean this implementation is, there are no prop drilling annoyances.

Let's now use this hook to show which of the Left Menu items are activate.

// src/components/MainMenu/index.tsx

import React from "react";
import { Link, useLocation } from "react-router-dom";

import { Drawer, List, ListItem, ListItemText } from "@material-ui/core";

const menuItems = [
  { label: 'Buttons', url: '/ui/buttons' },
  { label: 'Colour Palette', url: '/ui/colour-palette' },
  { label: 'Typogaphies', url: '/ui/typographies' },
]

function MenuItems({ setOpenMenu }: { setOpenMenu: React.Dispatch<React.SetStateAction<boolean>> }) {
  const { pathname } = useLocation();

  return (
    <List>
      {menuItems.map(({ label, url }) => (
        <ListItem
          button
          component={Link}
          key={label}
          onClick={() => setOpenMenu(false)}
          style={pathname === url ? { backgroundColor: '#40bfb4' } : undefined}
          to={url}
        >
          <ListItemText primary={label} />
        </ListItem>
      ))}
    </List>
  )
}

/* ...Rest of code */

Notes:

We've introduced the useLocation hook so we can use the pathname to validate if one of our links are active
We've added a style prop to the ListItem component so we can visually change the background colour if it is active.

useHistory vs useLocation

Sometimes you need access to the current pathname, derived from the Location object. It can be easy to confuse where to retrieve the current pathname from as both useHistory and useLocation expose it. But the truth of the matter is useLocation is the one to use in this case as it exposes the current state values.

Redirect

There might be times where your App's Information Architecture changes and you need to redirect users from 1 area to another. This is where Redirect comes in handy, you simply find the Route you want to target and define the Redirect component.

import React from "react";
import { Redirect, Route, RouteComponentProps, Switch, useRouteMatch } from "react-router-dom";

export default function Routes() {
  return (
    <Switch>
      <Redirect from="/ui/:name" to="/uiNew/:name" />
      <Route path="/uiNew/:name" component={UIPage} />
    </Switch>
  );
}

/* ...Rest of code */

Notes:

We've inserted the Redirect component before the Route Component
We've defined the from prop with the old URL we want to redirect from. Likewise we're defined the to prop to instruct where to redirect to.
We've updated the Route to contain the new pathname and the rest is business as usual.

🙏 Closing

At this stage your application should be wrapped with a Router Component.
You should have enough knowledge on how to setup your Applications routes, link between pages and use Router hooks to access parameterized data.

You are now ready to move onto the next episode where I’ll walk you through how to implement React Components, covering the following topics:

Component Fundamentals
Component Composition
Performance Considerations

Don't be shy, get in touch with us!

FED Talk! Episode 2: Material UI Theme

Quintin Maseyk — Tue, 18 May 2021 02:51:25 +0000

In today's episode we will step through how to implement your applications theme using Material UI's Theme Provider. We will configure everything from:

Typography
Breakpoints
Colours
Buttons
How to scaffold your App

Let's get started!

Table of Contents:

🤔 What's a Theme?
Theme Setup
- Configure Theme
Typography
- Type Scale
- Font Sizing
Breakpoints
- Configuration
- Accessing Breakpoints
- CSS Media Queries
- JS Media Queries
Colour Palette
- Choosing Your Colours
- Apply the Palette
Buttons
Scaffold Your App
- App Bar
- Body Content
- Main Menu Navigation
🙏 Closing

🤔 What's a Theme?

Themes are important as they define the look and feel of your overall application. A good theme engine will allow the development team to configure things once centrally, as opposed to repetitively.

The theme specifies the color of the components, darkness of the surfaces, level of shadow, appropriate opacity of ink elements, etc.

Themes let you apply a consistent tone to your app. It allows you to customize all design aspects of your project in order to meet the specific needs of your business or brand.

To promote greater consistency between apps, light and dark theme types are available to choose from. By default, components use the light theme type.
(@material-ui)

Here's a good example where the Design Manager of GitHub, Diana Mounter, talks in depth about the struggles they had trying to make create a Dark theme and where creating a centralised theme earlier would have made their lives much easier.

When the design systems team at GitHub implemented their colour system in 2017 they were working with Sass, trying to wrangle thousands of disconnected colour values into something more manageable to use. Now they're revisiting colour again, but this time with new tools, new customer goals, and more experience. In the age of dark mode, can what they've learned from CSS-in-JS and component APIs help them in their approach to color themeability? In this talk Diana covers lessons in color systems, theming APIs, and a bit of color theory along the way.

Find out more

Theme Setup

The first thing to do is wrap your Application with MUI's ThemeProvider component.

// src/app.tsx

import { CssBaseline, ThemeProvider } from '@material-ui/core';

export default function App() {
  return (
    <ThemeProvider> {/* Property 'theme' is missing... */}
      <CssBaseline />
      <h1>Design System</h1>
    </ThemeProvider>
  );
}

The above now wraps each of your app's child components with the Theme Provider, thus, exposing your theme via React's Context API, which we will later learn how to use.

Let's now create a new folder in your src directory called theme. Here is where we can store each of our theme configurations.

Create the following file:

// src/theme/index.tsx

import { createMuiTheme } from '@material-ui/core';

export default createMuiTheme({

})

The output of createMuiTheme will create a Theme object, which our newly added ThemeProvider Higher-order-Component (HoC) requires. Let's plug it in.

// src/app.tsx

import { CssBaseline, ThemeProvider } from '@material-ui/core';
import Theme from './theme';

export default function App() {
  return (
    <ThemeProvider theme={Theme}>
      <CssBaseline />
      <h1>Design System</h1>
    </ThemeProvider>
  );
}

Configure Theme

One of the really neat benefits of using MUI is that their TypeScript definitions are well documented. This is evident by using VSCode's "Go to definition" on any of their module exports for example if we dived into their createMuiTheme component, you will see something like this:

// node_modules/@material-ui/core/styles/createMuiTheme.d.ts

import { Breakpoints, BreakpointsOptions } from './createBreakpoints';
import { Mixins, MixinsOptions } from './createMixins';
import { Palette, PaletteOptions } from './createPalette';
import { Typography, TypographyOptions } from './createTypography';
import { Shadows } from './shadows';
import { Shape, ShapeOptions } from './shape';
import { Spacing, SpacingOptions } from './createSpacing';
import { Transitions, TransitionsOptions } from './transitions';
import { ZIndex, ZIndexOptions } from './zIndex';
import { Overrides } from './overrides';
import { ComponentsProps } from './props';

export type Direction = 'ltr' | 'rtl';

export interface ThemeOptions {
  shape?: ShapeOptions;
  breakpoints?: BreakpointsOptions;
  direction?: Direction;
  mixins?: MixinsOptions;
  overrides?: Overrides;
  palette?: PaletteOptions;
  props?: ComponentsProps;
  shadows?: Shadows;
  spacing?: SpacingOptions;
  transitions?: TransitionsOptions;
  typography?: TypographyOptions | ((palette: Palette) => TypographyOptions);
  zIndex?: ZIndexOptions;
  unstable_strictMode?: boolean;
}

export interface Theme {
  shape: Shape;
  breakpoints: Breakpoints;
  direction: Direction;
  mixins: Mixins;
  overrides?: Overrides;
  palette: Palette;
  props?: ComponentsProps;
  shadows: Shadows;
  spacing: Spacing;
  transitions: Transitions;
  typography: Typography;
  zIndex: ZIndex;
  unstable_strictMode?: boolean;
}

export default function createMuiTheme(options?: ThemeOptions, ...args: object[]): Theme;

We now know how to interface into this module and populate the ThemeOptions.

Typography

It's important to use the correct Typography for any given media, whether it be for Print, Digital, Low/High resolution devices.

Well defined typography should allow your viewers to clearly distinguish content and its formalities. For example, the font size of a H1 tag should be visually larger than that of a H2, likewise with H2 vs H3 and so on; this is called "Font Scaling". Find out more on the Type System.

Let's pick some fonts using Google Fonts, 1 bold for our headings and one other for the rest of our app.

Step 1: Find your desired header font

Navigate through their font library until you find one you like (I'm happy with "Krona One"). Then click into the font's box to navigate and read more about the font's details.

Step 2: Add the font to your "Selected families" tray

Proceeding with your font's selection, make sure to click "Select this style" to add it to your tray.

Step 3: Pair your font with one of their suggestions

A cool feature Google Fonts provide is that they give you a list of suggestive Pairings for your selected font. If none of the pairings work for you, go back to the home page and find another font. Once you are happy, make sure to add it to your tray.

Step 4: Embed your fonts to your App

The "Selected families" tray will then allow you to review your selected fonts as well as present you how to embed them in your App. In this case I would use their proposed <link> implementation mostly because they provide the <link rek="preconnect"> line.

The preconnect declaration helps improve page load speeds by instructing the browser to connect with another origin, thus hitting all of the connection constraints up front, rather then when the actual resource request gets called.
Find out more.

Copy and paste their code snippet into the <head> block.

// public/index.html

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="utf-8" />
  <meta name="description" content="Web site created using create-react-app" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="msapplication-TileColor" content="#231f20">
  <meta name="theme-color" content="#231f20">
  <link rel="apple-touch-icon" sizes="76x76" href="/apple-touch-icon.png">
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
  <link rel="manifest" href="/site.webmanifest">
  <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#40bfb4">
  <link rel="preconnect" href="https://fonts.gstatic.com">
  <link href="https://fonts.googleapis.com/css2?family=Jura&family=Krona+One&display=swap" rel="stylesheet">
  <title>Design System | QuinTRON</title>
</head>

<body>
  <noscript>You need to enable JavaScript to run this app.</noscript>
  <div id="root"></div>
</body>

</html>

This instructs the browser to request our Google fonts during the App's initial load. The fonts themselves will only be apparent once we bind the CSS Font-Families to our HTML. To do this we'll need to extend our theme by adding a Typography configuration.

MUI's Typography component allow configuration for the following variants (I've added their default HTML element mapping as inline comments):

export type Variant =
  | 'h1'        // maps to <h1>
  | 'h2'        // maps to <h2>
  | 'h3'        // maps to <h3>
  | 'h4'        // maps to <h4>
  | 'h5'        // maps to <h5>
  | 'h6'        // maps to <h6>
  | 'subtitle1' // maps to <h6>
  | 'subtitle2' // maps to <h6>
  | 'body1'     // maps to <p>
  | 'body2'     // maps to <p>
  | 'caption'   // maps to <span>
  | 'button'    // maps to <button>
  | 'overline'; // maps to <span>

You can also change the default HTML mappings by implementing the following example:

// theme/index.tsx

const theme = createMuiTheme({
  props: {
    MuiTypography: {
      variantMapping: {
        body1: 'span', // traditionally set as <p>
        body2: 'span', // traditionally set as <p>
      }
    }
  }
});

⚠️

I highly recommend you read all of MUI's Typography definitions and rules for each of the Variants above. They do a good job in explaining how, when and where to use it in your App.

Read more here

We can create our Typography file to configure each of the variants definitions.

// stc/theme/typography.tsx

import { TypographyOptions } from '@material-ui/core/styles/createTypography';

export const typography: TypographyOptions = {
  h1:         { fontFamily: "'Krona One', sans-serif" },
  h2:         { fontFamily: "'Krona One', sans-serif" },
  h3:         { fontFamily: "'Krona One', sans-serif" },
  h4:         { fontFamily: "'Krona One', sans-serif" },
  h5:         { fontFamily: "'Krona One', sans-serif" },
  h6:         { fontFamily: "'Krona One', sans-serif" },
  subtitle1:  { fontFamily: "'Jura', sans-serif" },
  subtitle2:  { fontFamily: "'Jura', sans-serif" },
  body1:      { fontFamily: "'Jura', sans-serif" },
  body2:      { fontFamily: "'Jura', sans-serif" },
  caption:    { fontFamily: "'Jura', sans-serif" },
  button:     { fontFamily: "'Jura', sans-serif" },
  overline:   { fontFamily: "'Jura', sans-serif" },
}

Then add your Typography config to the Theme module.

// src/theme/index.tsx

import { createMuiTheme } from '@material-ui/core';
import { typography } from './typography';

export default createMuiTheme({
  typography
})

Your Google Font is now bound to MUI Typography components! Let's add some content to our App and test out how it looks.

// src/app.tsx

import { CssBaseline, ThemeProvider } from '@material-ui/core';

import Theme from './theme';

export default function App() {
  return (
    <ThemeProvider theme={Theme}>
      <CssBaseline />
      <h1>Heading 1</h1>
      <h2>Heading 2</h2>
      <h3>Heading 3</h3>
      <h4>Heading 4</h4>
      <h5>Heading 5</h5>
      <h6>Heading 6</h6>
      <p>Body content</p>
      <button>Button label</button>
      <caption>Caption text</caption>
    </ThemeProvider>
  );
}

This is what is looks like:

🤔 Hm, I don't see my header font. Ah-huh, it's because I was using the default HTML tags, not MUI's Typography component. Let's convert them like so:

// src/app.tsx

import { Button, CssBaseline, ThemeProvider, Typography } from '@material-ui/core';

import Theme from './theme';

export default function App() {
  return (
    <ThemeProvider theme={Theme}>
      <CssBaseline />
      <Typography variant="h1">Heading 1</Typography>
      <Typography variant="h2">Heading 2</Typography>
      <Typography variant="h3">Heading 3</Typography>
      <Typography variant="h4">Heading 4</Typography>
      <Typography variant="h5">Heading 5</Typography>
      <Typography variant="h6">Heading 6</Typography>
      <Typography variant="body1">Body content 1</Typography>
      <Typography variant="body2">Body content 2</Typography>
      <Typography variant="subtitle1">Subtitle 1</Typography>
      <Typography variant="subtitle2">Subtitle 2</Typography>
      <Typography variant="caption">Caption text</Typography>
      <Typography variant="overline">Overline text</Typography>
      <Button variant="contained">Button Contained</Button>
      <Button variant="outlined">Button Outlined</Button>
      <Button variant="text">Button Text</Button>
    </ThemeProvider>
  );
}

This is now what is looks like:

❤️ Now that's what the fonts should look like!

Type Scale

The next obvious step is to implement font scaling across all of our Typography set to provide consistency across the app, for all screen sizes and resolutions.

Font Sizing

Material-UI uses rem units for the font size. The browser element default font size is 16px, but browsers have an option to change this value, so rem units allow us to accommodate the user's settings, resulting in a better accessibility support. Users change font size settings for all kinds of reasons, from poor eyesight to choosing optimum settings for devices that can be vastly different in size and viewing distance.

To change the font-size of Material-UI you can provide a fontSize property. The default value is 14px.

Learn more

There are two ways to set your app's Font Sizing:

Manually declaring each of the variants font sizes, for each of your desired Break-Points in your Typography file. 😱
Using MUI's nifty responsiveFontSizes helper to do it for us! 🍾

For this example we will implement option 2 as it reduces the amount of custom code we need to maintain and defines all the font sizes for us for each breakpoint. An interactive demo on how this functionality works can be found here

All we have to do is wrap our theme with their function.

// theme/index.tsx

import { createMuiTheme, responsiveFontSizes } from '@material-ui/core';

import { typography } from './typography';

export default responsiveFontSizes(createMuiTheme({
  typography
}))

Our font sizes are now responsive! The following screenshots illustrate how the H1's font-size grows from mobile through to desktop, each configured against the small (sm), medium (md) and large (lg) breakpoints.

breakpoint:sm

breakpoint: md

breakpoint: lg

💡
MUI's design principle work off a Mobile-First approach, for example, the font-size style for Large breakpoint overrides that of the Medium and Small (default) font-sizes.

If you wish to change the strength of the font size's resize amount between breakpoints, you can add a factor option to the responsiveFontSizes function.

// theme/index.tsx

import { createMuiTheme, responsiveFontSizes } from '@material-ui/core';

import { typography } from './typography';

export default responsiveFontSizes(createMuiTheme({
  typography
}), {
  factor: 1 // [default is 2] The higher the value, the less difference there is between font sizes on small screens. The lower the value, the bigger font sizes for small screens. The value must be greater than 1.
})

Breakpoints

For optimal user experience, material design interfaces need to be able to adapt their layout at various breakpoints. Material-UI uses a simplified implementation of the original specification.

The breakpoints are used internally in various components to make them responsive, but you can also take advantage of them for controlling the layout of your application through the Grid and Hidden components.

Configuration

MUI's Theme implements the following default breakpoints:

xs, extra-small: 0px
sm, small: 600px
md, medium: 960px
lg, large: 1280px
xl, extra-large: 1920px

I've personally never had to change any of the Breakpoint settings even though you are able to reconfigure them.

Information on how to customize Breakpoints can be found here.

📝

Take mental note of the breakpoint keys [xs, sm, md, lg, xl] as you will use them in the future.

Accessing Breakpoints

When you get to the stage of developing components you'll eventually have to solve responsive layout issues to make your App accessible and as fluid as possible.

MUI offer many ways for you to interface into the Theme's breakpoint state whether you wish to statically style your component and its breakpoint changes, or observe breakpoint changes in your Component to logically do something. Let's go through some examples.

CSS Media Queries

For this example imagine you have a Card component which has a heading, some text and then a call-to-action Button at the bottom. You are then tasked to style the Button against different breakpoints.

Pseudo train of thought

[breakpoints equal to or less than sm] the button should span across the full width of the card,
[breakpoints equal to or greater than md] the button should anchor to the right using its original width.
[breakpoints equal to or greater than lg] the button should anchor to the right using its original width, and its padding should be larger.

Final implemtation

// Example: CSS Media Queries

const styles = theme => ({
  button: {
    [theme.breakpoints.down('sm')]: {
      width: '100%'
    },
    [theme.breakpoints.up('md')]: {
      width: 'auto'
    },
    [theme.breakpoints.up('lg')]: {
      paddingLeft: '4rem',
      paddingRight: '4rem'
    },
  },
});

Few things to note:

breakpoints is a property exposed from our injected theme (via the ThemeProvider HoC)
breakpoints have 4 functions you can use to select your target breakpoints:
theme.breakpoints.up(key)
theme.breakpoints.down(key)
theme.breakpoints.only(key)
theme.breakpoints.between(start, end)
Declare your breakpoints from smallest to largest as to retain MUI's Mobile-First design principle. By not doing this you could experience unexpected behavior.

JS Media Queries

For this example imagine you have a Table which has many columns and is read from left to right. This table reads really well on larger screens however the designer has rejigged the Table for mobile screens, thus a second rendition of the Table should be rendered in this case.

Pseudo train of thought

[breakpoints equal to or less than sm] should render the MobileTable, otherwise the LargerTable should be rendered.

Final implementation

// Example: JS Media Queries

import { useTheme } from '@material-ui/core/styles';
import useMediaQuery from '@material-ui/core/useMediaQuery';

function TableWrapper() {
  const theme = useTheme();
  const mobileBreakpoint = useMediaQuery(theme.breakpoints.down('sm'));

  if (mobileBreakpoint) {
    return <MobileTable />
  }
  return <LargerTable />
}

Few things to note:

The useTheme hook is defined so the TableWrapper component has access to the app's Theme.
The useMediaQuery hook is defined and parameterized with my desired breakpoint for the hook to observe. Its initial value is either true or false, depending on the clients calculated dimensions.
useMediaQuery observe the windows Resize event and will internally recompute the hooks value if the theme's current breakpoint value changes.
Remember breakpoints.down(key), breakpoints.up(key) includes the key as part of its Boolean check.

Learn more on useMediaQuery.

Colour Palette

Colour exists and most are fortunate to witness its array and uses in the world. If used well it can promote your brand and cognitively remind people of your brand, it can indicate a level of severity and attract the eye. Ultimately colour has meaning.

MUI's Theme allow you to configure a palette, which is a make up "colour intention". Here are the colour intentions and their uses.

primary - used to represent primary interface elements for a user. It's the colour displayed most frequently across your app's screens and components.
secondary - used to represent secondary interface elements for a user. It provides more ways to accent and distinguish your product. Having it is optional.
error - used to represent interface elements that the user should be made aware of.
warning - used to represent potentially dangerous actions or important messages.
info - used to present information to the user that is neutral and not necessarily important.
success - used to indicate the successful completion of an action that a user triggered. If you want to learn more about colour, you can check out the colour section.

The following screenshot shows each colour intention and their default values:

Choosing Your Colours

MUI's the gift which just keeps giving! The Material Design team have built a "Color Tool" which you can use to plug in your specific colours and visually see them against MUI's base components. The tool also has an Accessibility feature which I encourage you to use as it will report the legibility of your colours.

Material Design: Color Tool

I will continue to use the Mechanical Rock brand colours:

Primary: #40BFB4
Secondary #E15554

The tool will automatically calculate the Light and Dark values from your provided main colour.

🤔

The Accessibility report suggests "White Text" on each of my Primary variants are not legible; the same is mostly true for the Secondary variants. Remind yourself of this in future.

Apply the Palette

Once you have finalized your Primary and Secondary colours you can then configure them into your Theme. We will create a new Palette file to manage this change (like we did for Typography).

// theme/palette.tsx

import { PaletteOptions } from '@material-ui/core/styles/createPalette';

export const palette: PaletteOptions = {
  primary: {
    // light: will be calculated from palette.primary.main,
    main: '#40bfb4',
    // dark: will be calculated from palette.primary.main,
    // contrastText: will be calculated to contrast with palette.primary.main
  },
  secondary: {
    // light: will be calculated from palette.primary.main,
    main: '#e05450',
    // dark: will be calculated from palette.secondary.main,
  },
  // Used by `getContrastText()` to maximize the contrast between
  // the background and the text.
  contrastThreshold: 3,
  // Used by the functions below to shift a color's luminance by approximately
  // two indexes within its tonal palette.
  // E.g., shift from Red 500 to Red 300 or Red 700.
  tonalOffset: 0.2,
}

As the comments in the above code snippet suggest, you can let MUI calculate the Light/Dark values for you for free, otherwise manually add them for each Primary and Secondary objects.

Even if your chosen colours have been reported eligible in the "Color Tool" there is still a chance your foreground text does not contrast well against background shades on your surfaces. The contrastThreshold property allows you to amplify or soften the contrast of your text against the background colour.

If you wish to dim the lights or make a colour more vivid during events such as hovering over a button, you can tweak the amount against the tonalOffset property.

Let's add a colour section to our App by doing the following:

// src/ui/ColourPalette/index.tsx

import React from 'react';

import { Box, Grid, Typography } from '@material-ui/core';

function ColourBox({ intention, variant }: { intention: string; variant: string; }) {
  const bgColor = `${intention}.${variant}`;
  const color = intention === 'text' ? 'background.paper' : `${intention}.contrastText`;
  return (
    <Grid item xs={12} sm={4}>
      <Box bgcolor={bgColor} color={color} p={4}>
        <strong>{bgColor}</strong>
      </Box>
    </Grid>
  )
}

const palette = [
  { intention: 'primary', variant: 'main' },
  { intention: 'secondary', variant: 'main' },
  { intention: 'error', variant: 'main' },
  { intention: 'warning', variant: 'main' },
  { intention: 'info', variant: 'main' },
  { intention: 'success', variant: 'main' },
  { intention: 'text', variant: 'primary' },
  { intention: 'text', variant: 'secondary' },
  { intention: 'text', variant: 'disabled' }
]
export default function ColourPalette() {
  return (
    <>
      <Typography variant="h2">Colour Palette</Typography>
      <br />
      <Grid container spacing={1}>
        {palette.map((p, i) => <ColourBox key={i} {...p} />)}
      </Grid>
    </>
  )
}

Then add the new section to our App:

// src/app.tsx

import { CssBaseline, Divider, ThemeProvider } from '@material-ui/core';

import Theme from './theme';
import ColourPalette from './ui/ColourPalette';
import Typography from './ui/Typographies';

export default function App() {
  return (
    <ThemeProvider theme={Theme}>
      <CssBaseline />
      <Typography />
      <Divider />
      <ColourPalette />
    </ThemeProvider>
  );
}

You should end up seeing this:

Buttons

Buttons allow users to take actions, and make choices, with a single tap. (@material-ui)

MUI offer 3 variations of buttons, Contained, Text, Outlined.

Contained Button

Contain buttons should be used for primary user actions. They are pronounced and elevated on the surface.

Text Button

Text buttons are typically used for less-pronounced actions, including those located in Dialogs and Cards. In cards, text buttons help maintain an emphasis on card content.

Outlined Button

Outlined buttons are medium-emphasis buttons. They contain actions that are important, but aren’t the primary action in an app. Outlined buttons are also a lower emphasis alternative to contained buttons, or a higher emphasis alternative to text buttons.

Let's add a button section to our App by doing the following:

// ui/Buttons/index.tsx

import React from 'react';

import { Button, Container, Typography } from '@material-ui/core';

export default function Buttons() {
  return (
    <>
      <Typography variant="h2">Buttons</Typography>
      <br />

      <Container maxWidth="xs">
        <Typography variant="subtitle1" align="center">Contained</Typography>
        <Button variant="contained" color="default">Default</Button>
        <Button variant="contained" color="primary">Primary</Button>
        <Button variant="contained" color="secondary">Secondary</Button>
        <Button variant="contained" color="primary" disabled>Disabled</Button>
      </Container>
      <br />

      <Container maxWidth="xs">
        <Typography variant="subtitle1" align="center">Text</Typography>
        <Button variant="text" color="default">Default</Button>
        <Button variant="text" color="primary">Primary</Button>
        <Button variant="text" color="secondary">Secondary</Button>
        <Button variant="text" color="primary" disabled>Disabled</Button>
      </Container>
      <br />

      <Container maxWidth="xs">
        <Typography variant="subtitle1" align="center">Outlined</Typography>
        <Button variant="outlined" color="default">Default</Button>
        <Button variant="outlined" color="primary">Primary</Button>
        <Button variant="outlined" color="secondary">Secondary</Button>
        <Button variant="outlined" color="primary" disabled>Disabled</Button>
      </Container>
    </>
  )
}

Don't forget to add it to your App.tsx file to see the new content!

We should see something like this:

Scaffold Your App

Setting your app's initial layout can be daunting. Even though most website layouts are quite consistent these days, there is more than 1 way to skin a cat! Too many website implementations lack well schematic HTML, making me think there is a gap of knowledge on this subject. For example websites which have multiple H1 tags, broken header hierarchy, unnecessary div usage which should be replaced with better purposed tags.

👍 Our goal as Front-End developers is to make everything we build accessible!

Before we can start building out our layout we need to know where the main landmarks are. Will the main menu navigation be on the top of the page (will it be fixed?), or will it be anchored on the left of the page?
What type of content are you required to display? Blog-like content where content is best presented in the center channel or multimedia, where content can be tiled.

For our case the scaffold will look like this for mobile:

And for desktop:

App Bar

The App Bar displays information and actions relating to the current screen.
It provides content and actions related to the current screen.
It’s used for branding, screen titles, navigation, and actions.

Learn more

Create a new file to manage your App Bar:

// src/components/AppBar/index.tsx

import React from 'react';

import { AppBar as MuiAppBar, IconButton, Toolbar, Typography } from '@material-ui/core';
import { MenuRounded } from '@material-ui/icons';

export default function AppBar() {
  return (
    <MuiAppBar color="primary" position="sticky">
      <Toolbar>
        <IconButton edge="start" aria-label="menu">
          <MenuRounded />
        </IconButton>
        <Typography variant="h6">
          Component Library
        </Typography>
      </Toolbar>
    </MuiAppBar>
  )
}

Few things to note:

We have to cast the imported AppBar module to a new name MuiAppBar so that we are able to export our own version of the AppBar going forward.
We implement the [position="sticky"] prop against the MuiAppBar. This is so the AppBar will stick to the top of the viewport, even when you scroll beyond its initial position.
We implement the [edge="start"] prop against the IconButton. This will apply some css to anchor the icon to the left, minus its original margin offset.

We end up with this:

Body Content

Here is where most of your audience will spend their time discovering, interacting or researching for information in your App. The body content itself can obtain many layouts internally, but what's important its abstract layer should be consistent.

Create a new file to manage your Body Content:

// src/components/BodyContent/index.tsx

import React from 'react';

import { Divider, makeStyles } from '@material-ui/core';

import ColourPalette from '../../ui/ColourPalette';
import Typographies from '../../ui/Typographies';

const useStyles = makeStyles(() => ({
  root: {
    margin: '0 auto',
    maxWidth: '57rem',
    padding: '2rem 0'
  }
}))

export default function BodyContent() {
  const classes = useStyles();

  return (
    <main className={classes.root}>
      <Typographies />
      <Divider />
      <ColourPalette />
    </main>
  )
}

Few things to note:

We've created our first CSS-in-JSS example. We had to do this to define some styles against the root element of this component, <main>. makeStyles export the computed styles as a hook, when we've assigned to a scoped variable named useStyles. useStyles is then declared inside the body of our BodyContent component so we have access to it.
margin: '0 auto' will make sure the <main> block is centered in the page
maxWidth: '57rem' will set the maximum width of the <main> block, I felt represented a good readable column width for larger screens.
padding: '2rem 0' will apply a consistent 2rem gutter at the top and bottom of the <main> block.
We've since migrated the Typographies and ColourPalette components from the app.tsx file into this file.
Note the use of the HTML main Tag. It's a more accurate tag to use in this case as it encapsulates the intent for the rest of the content.

Learn more on the main tag

Here's a desktop screenshot of showing the box-model of our <main> element:

Main Menu Navigation

The main menu is the primary way for users to navigate around your App. It should contain all the main areas of the App and indicate where the user currently sits in the hierarchy.

Create a new file to manage your Main Menu Navigation:

// src/components/MainMenu/index.tsx

import React from 'react';

import { Drawer, List, ListItem, ListItemText } from '@material-ui/core';

function MenuItems() {
  return (
    <List>
      {['1', '2', '3'].map(item => (
        <ListItem button key={item}>
          <ListItemText primary={`Menu Item #${item}`} />
        </ListItem>
      ))}
    </List>
  )
}

type Props = {
  openMenu: boolean;
  setOpenMenu: React.Dispatch<React.SetStateAction<boolean>>;
}

export default function MainMenu({ openMenu, setOpenMenu }: Props) {
  return (
    <nav aria-label="main menu navigation">
      <Drawer
        anchor="left"
        disablePortal
        onClose={() => setOpenMenu(false)}
        open={openMenu}
        variant="temporary"
      >
        <MenuItems />
      </Drawer>
    </nav>
  );
}

Few things to note:

We're using MUI's Drawer component to hold our Menu Items content.
[anchor="left"] prop is used to declare where we would like the Menu it transition from.
I've personally declared [disablePortal=true] here so the HTML lives inside of the <nav> element, thus, making it more accessible and schematically correct.
The onClose callback function gets invoked only if the background click-away-listener is present; set by the [variant="temporary"] property.
[open=true] will transition the Menu in and the opposite will transition the Menu out.

We then have to colocate the MainMenu with our AppBar component as it has the Menu button we need to wire up.

// src/components/AppBar/index.tsx

import React from 'react';

import { AppBar as MuiAppBar, IconButton, Toolbar, Typography } from '@material-ui/core';
import { MenuRounded } from '@material-ui/icons';

import MainMenu from '../MainMenu';

export default function AppBar() {
  const [openMenu, setOpenMenu] = React.useState(false);

  return (
    <>
      <MuiAppBar color="primary" position="sticky">
        <Toolbar>
          <IconButton
            edge="start"
            aria-label="menu"
            onClick={() => setOpenMenu(state => !state)}
          >
            <MenuRounded />
          </IconButton>
          <Typography variant="h6">
            Component Library
          </Typography>
        </Toolbar>
      </MuiAppBar>
      <MainMenu openMenu={openMenu} setOpenMenu={setOpenMenu} />
    </>
  )
}

💡 We can better manage this type of state using React's Contextual API. This will be covered in a future episode.

We end up with this:

🙏 Closing

At this stage your application should be wrapped with a Theme Provider.
You should have enough knowledge on how to override the styles of MUI components as well as how to create your own styles along side your own components.

You are now ready to move onto the next episode where I’ll be walking you through how to implement Routing in your app, covering the following topics:

How to setup Routing in your app,
Routes with parameters,
Route hooks,
Route transitions

Don't be shy, get in touch with us!

FED Talk! Episode 1: Getting Started with React & Material UI

Quintin Maseyk — Tue, 04 May 2021 03:28:30 +0000

I’ve been meaning to write a Front-End Developer (FED) series for quite some time now. Having worked in many industries, building many Web Apps on different stacks and Design Systems, I’m here to share my learnings and hopefully you will get something out of it.

These days it's very easy for new developers to get up and running using tooling such as create-react-app. Tooling such as this is great as it speeds up repetitive tasks and automates all of a React's initial constructs, enabling developers to be able to build, test and deploy their applications. But, great tooling can also restrict one's knowledge of understanding what actually happens during and after its compilation.

This series will contain many episodes, each ordered with hope to equip you with a typical FED experience on how to build React Apps. As it stands the following subjects have been identified:

Episode 1: Getting Started
Episode 2: Theme Providers
Episode 3: Routing
Episode 4: Testing and Developing components

In today's episode we will bootstrap a React application going into detail during each of the steps. You will be provided a mixture of code snippets, screenshots and external references along the way.

Table of Contents:

💭 Mindset
🤔 Which UI Library?
- Comparison
🚀 Let's get started!
- Create React App
- Public Folder
- Source Folder
- package.json file
⌨️ Getting Started with Material UI
- @material-ui/core
- @material-ui/icons
🔧 App Preparation
- CssBaseline
- Understanding the “Box Model”
- What does "box-sizing" actually do?
💆 Heads Up!
- Charset
- Title
- Favicon
- Viewport
🙏 Closing

💭 Mindset

Does what you’re building already have an affiliated Design System (DS), or a living Style Guide, or at least some kind of Branding documentation?

If the answer is yes, that’s great, you have a basis to work from and extend off, for example if you already have a Component Library, you can start building your interface with existing Components, rather than building from scratch. My mentality in this case is

how can I consume the existing styles with least amount of friction?
how can I contribute back so others can benefit?

If the answer is no, that’s still okay, instead you have prime opportunity to centralize the App’s DS artifacts! My mentality in this case is a bit more involved and requires team/company wide structure to help formulate a cross functional Design → Developer process. We will cover this in more detail throughout the series.

For the rest of this series we will assume there is no DS, instead, we will build one DS alongside our functional React App! That's the cool thing about this, when you are creating a new App, it’s better practice to create one from the get-go as it helps with testing, its living documentation, it can make design discussions easier etc.

I’m flinging the word “Design System” too loose here. We’ll be creating a Living Component Library (a subset of a Design System) as trying to build full a Design System is more than code artifacts.

🤔 Which UI Library?

There has and always will be a handful of UI libraries floating around, battling for top adoption rates but before we pick a library let's be clear what a UI library is and why they are necessary.

A UI library is a central repository where both design artifacts and developed components are showcased. They contain all the essential building blocks an application requires to start it's creation, things like: Typography, Buttons, Links, Cards, Lists, Tables, Layouts, Responsive design etc. Good UI libraries make it easy for the consumer to define their own Themes and Components, are testable, are accessible and are well documented.

Do you really want to spend your valuable time re-inventing a Button every.. single.. time!?

What’s important is to understand the basis of each of the UI libraries, at the end of the day they are just that: a library. The onus is on you to determine:

When was it created?
What does their future roadmap entail and will they continue to support it?
What major version is it on?
How much community support does it have?
What browsers do they support and does it align with yours?
How Accessible is the library?
What is their documentation like?
Does it align with your tech stack (Typescript? SSR? Testable?)
Can you contribute back?

Comparison

I’ve chosen 3 libraries to compare, each slightly different in their philosophies.

Snapshot taken as of April, 2021.

	Bootstrap	Material UI	Tailwind CSS
Birth	2011	2014	2017
Latest Version	4.6.0	4.11.3	2.0.1
Weekly Downloads	2.2M	1.3M	530K
Contributors	1150+	2050+	150+
Methodology	Object Oriented CSS	Object Oriented CSS	Utility-First CSS
Processor	Pre Process	Pre Process	Post Process
Library Size	~308kb		~27kb
React Version		^16.8.0
Typescript?		(v3.2+)
Browser Support	IE: 11 Edge: >= 80 Firefox:>= 60 Chrome: >= 60 Safari: >= 10	IE: 11 Edge: >= 14 Firefox: >= 52 Chrome: >= 49 Safari: >= 10	IE: Edge: Firefox: Chrome: Safari:
Roadmap	Github Discussions	MUI Roadmap	Github Discussions
Design Figma Artifacts	Figma link	Figma link	Figma link

In all my use cases I’ve found Material UI (MUI) to have everything I need. The amount of developer tools their library provide are perfect for my React apps. So for the rest of this journey, we will be focusing on building a React App, using Material UI to help us.

❗ The point of this is to not sway you from the other UI libraries, instead, it was to get you thinking, to keep comparing and seeing what else is out there.

🚀 Let's get started!

Create React App (CRA)

CRA allow developers to get started immediately, without having to configure tooling such as Webpack or Babel. Traditionally developers would have to manually configure Webpack (or the like) with their React App which generally required substantial knowledge from the developer to understand how to:

build the source code,
locally host the app,
setup testing,
configure production vs non-production build environments
localhost cache-management,
configure service-worker, and much more

create-react-app --template typescript mui-app
cd mui-app

The following folder structures should be shown in your code editor (I’m using VSCode).

Public Folder

Source Folder

package.json file

More information on how the scripts work can be found here: https://create-react-app.dev/docs/available-scripts

⌨️ Getting Started with Material UI

Our app will be using both MUI core module as our Component Library and Theme engine, along with MUI icon module as our Icon library.

@material-ui/core

The Core library contains all your base needs, including:

Components
- Layouts
- Inputs
- Navigation
- Surfaces
- Feedback
- Data Display
- Utils
- Lab
Breakpoint definitions,
Theme engine,
Server Side Render Capability,
A CSS-in-JS solution unlocking many great features (theme nesting, dynamic styles, self-support, etc.)

npm install @material-ui/core

@material-ui/icons

The Icons library includes over a thousand icons, conveniently exposed as SvgIcon components for your consumption. We will dive into this library next episode.

npm install @material-ui/icons

A searchable list of all their icons can be found here: https://material-ui.com/components/material-icons/

Their SVGs come available in a few variations:

Filled	Outlined	Rounded	Two Tone	Sharp

If their SVG library does not satisfy your needs, MUI have conveniently created a component <Icon /> where you can inject any of Font Awesome classes into the component.

<Icon className="fa fa-plus-circle" />

However, if you use the <Icon /> component, be mindful of accessibility requirements. If your Icon has semantic meaning you are advised to include supporting text around it like so:

<Icon className="fa fa-plus-circle" />
<Typography variant="srOnly">Create a user</Typography>

For this series we will be using MUI Icons, which inherently use (a richer, accessible component)

🔧 App Preparation

Now that the core libraries have been installed we would then remove all the demonstration content from the src/App.tsx file. Following that, we should start to shape our App’s shell by doing the following.

CssBaseline

Use the CssBaseline component to kickstart an elegant, consistent, and simple baseline to build upon.

Edit your App.tsx file to look something like:

Upon saving those changes and loading your App, you’ll notice a new <style> tag being injected in the <head>:

This is configuring the browser to print as consistent as it can across all browsers.

Page

The <html> and <body> elements are updated to provide better page-wide defaults. More specifically:

The margin in all browsers is removed.

The default Material Design background color is applied. It's using theme.palette.background.default for standard devices and a white background for print devices.

Layout

box-sizing is set globally on the <html> element to border-box. Every element—including *::before and *::after are declared to inherit this property, which ensures that the declared width of the element is never exceeded due to padding or border.

Typography

No base font-size is declared on the <html>, but 16px is assumed (the browser default). You can learn more about the implications of changing the <html> default font size in the theme documentation page.

Set the theme.typography.body2 style on the <body> element.
Set the font-weight to theme.typography.fontWeightBold for the <b> and <strong> elements.
Custom font-smoothing is enabled for better display of the Roboto font.

Learn more

Understanding the “Box Model”

Every element sitting in the Document Object Model (DOM) has been computed in the CSS engine predefined by a set of properties. Selecting elements using the browsers Developer Tools → Inspect function, you’ll noticed the element’s Box Model being rendered as:

Note how the box has been defined, described from outside working in:
margin → border → padding → content

Each time you create a new element or update some styles try to think about how the changes can disrupt the Box Model, thus, the content flow.

💡 Whilst you’re working on styling an element, try to visualise the box-model output in your head, then see if it your guess is right!

What does "box-sizing" actually do?

You may have noticed the CSSBaseline style printed some box-sizing style declarations. I've created the following example so you can visually see the differences.

Let's say we have 3 square boxes flowing in a row with all the same dimensions.

The following boxes will be rendered:

And its box-model will look like:

Isn’t it strange how the div grows beyond its explicitly defined width/height of 100px?

By default the browser uses box-sizing: content-box, this means the width/height are a calculated value of the elements width (100px), padding (20px left, 20px right), border (20px left, 20px right), totaling 180px in this case.

By appending the box-sizing: border-box; property to each of the 3 boxes, the following will be rendered:

Notice the content area itself shrinks (blue square), but everything else stays the same? That’s the power of applying box-sizing: border-box; across the app. It sets an opinionated view on how content can be constructed throughout the app. I use this implementation as it stops me from having to calculate dimensions in my head, all I have to do now is provide a width and height and we’re good to go.

💆 Heads Up!

It’s important to keep your webpage’s Meta information up-to-date as a lot of the information in the <head> help define the webpage’s meta-data. This data can be used for many things such as:

Describing your page’s content to Web Crawlers (description, author, content type). This is to help with Search Engine Optimisations (SEO)
Declaring your documents charset
Setting your browser tab Title and Favicon
Setting your App as a Progressive Web App (PWA)
Configuring Social Media outputs (og:) and Search representations

Open and edit the following file public/index.html

Charset

Charset stands for Character Sets, it instructs the browser to compute the rest of the document with the defined charset. Example charsets are: Numb, ASCII, ANSI, 8859, UTF-8.

The HTML5 specification encourages web developers to use the UTF-8 character set!

This has not always been the case. The character encoding for the early web was ASCII.

Later, from HTML 2.0 to HTML 4.01, ISO-8859-1 was considered as the standard character set.

With XML and HTML5, UTF-8 finally arrived and solved a lot of character encoding problems.

Learn more

<head>
  ...
  <meta charset="UTF-8" />
</head>

Title

The title tag is a mandatory, text-only tag which sets the document’s title and is visible in your browsers Tab, History & Bookmarks.

🌶️ Hot Tips!

Go for a longer, descriptive title (avoid one- or two-word titles)

Search engines will display about 50-60 characters of the title, so try not to have titles longer than that

Do not use just a list of words as the title (this may reduce the page's position in search results)

So, try to make the title as accurate and meaningful as possible!

<head>
  ...
  <title>Design System | QuinTRON</title>
</head>

The following will output:

Favicon

A favicon is where you have the ability to brand your website/application. A well defined favicon gets used in browser Tabs, Bookmarks, PWA Install-to-desktop files, PWA Loading Screens, Offline files. They may seem like such a little thing, but all the little things add up to making your brand stand out!

I use realfavicongenerator to generate my favicon set. It’s a great online tool because it emulates how it would look in all devices and browsers. Taking it further, their website also allow you to customise the PWA manifest file, better declaring things like your brand’s colours.

After following their generation process you’ll be provided a zip file which have all the static resources required for you to host it in your public/ folder.

You are then required to update your public/index.html file’s head tag with the following:

Replace the former meta tags and links with their generated code.

<head>
  ...

  <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
  <link rel="manifest" href="/site.webmanifest">
  <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#40bfb4">
  <meta name="msapplication-TileColor" content="#40bfb4">
  <meta name="theme-color" content="#40bfb4">
</head>

I end up with this:

Viewport

Last thing to cover is the viewport meta tag.

The viewport is the user's visible area of a web page.

The viewport varies with the device, and will be smaller on a mobile phone than on a computer screen.

Before tablets and mobile phones, web pages were designed only for computer screens, and it was common for web pages to have a static design and a fixed size.

Then, when we started surfing the internet using tablets and mobile phones, fixed size web pages were too large to fit the viewport. To fix this, browsers on those devices scaled down the entire web page to fit the screen.

Learn more

Mobile: without viewport declaration	Mobile: with viewport declaration

As you can see the screenshot on the right neatly fits the maximum content into the devices viewport width. Obviously you’ll need to better style content for mobile, but that’s beside the point.

  <meta name="viewport" content="width=device-width, initial-scale=1" />

This gives the browser instructions on how to control the page's dimensions and scaling.

The width=device-width part sets the width of the page to follow the screen-width of the device (which will vary depending on the device).

The initial-scale=1 part sets the initial zoom level when the page is first loaded by the browser.

Lean more.

🙏 Closing

At this stage you should have the shell of a prosperous React App and have gained foundational knowledge of its make-up.

You are now ready to move onto the next episode where I’ll be walking you through how to implement a Theme provider in your app, covering everything from:

Typography,
Colours,
MUI theme and component overrides,
Responsive design

Don't be shy, get in touch with us!