Getting Started

Components overview

• A good place to start is by reading the overview of how to do high level screen layout with Recipe.
• Most Recipe components are opinionated about how to layout their child content. However in some cases you may need to use Layout to control the horizontal layout of individual components across multiple breakpoints.
• If you want to see what's available in Recipe, you can browse all components.
• Recipe components use consistent patterns for properties; you'll find various components use similarly named properties like title or value when the usage is equivalent across the components. Certain properties will also have a consistent shape wherever they are found. For example, the breadcrumb and tabs properties on Page Header and the home and links properties on Navigation accept a common "link" shaped object that accepts a url as an href or a Router compatible Link.
• Principles for using Recipe

When to consider building something new

Squads should challenge themselves to use the design system as much as possible. Designers should seek feedback on consistency and emerging patterns as a core aspect of design reviews. Engineers and PMs should ask questions if they see a proposed design that is not using Recipe.

However, Recipe is still a young design system and has plenty of room to evolve. We welcome ideas for new components and extensions of existing ones. We want to evolve the system in a thoughtful way so that we can main consistency.

Here are some things to consider when proposing a change to Recipe:

• Is this pattern general enough to apply to applications other than the one you are currently working on?
• Have you identified three or more situations where your proposed component could be used? These don't have to be all new cases, they could include situations where Recipe already has a solution but you think your proposed one is better for the user.

• Have you thought about the "distance" between this pattern and related patterns that are already in Recipe?

  • Can you provide clear guidance to designers and developers about when to choose this variation vs. the ones that are already available?
  • Will it be predictable to the user when they will see this variation vs. the ones that are already available?

Recipe themes

Recipe v14 introduces extendable Material UI themes using emotion. As new components are introduced and current components are updated, they will use these supported themes. A future version of Recipe will remove all legacy themes once all components have migrated to using these themes.

Supported themes

• ezTheme
• ezMarketplaceTheme - extends ezTheme
• ezFulfillmentTheme - extends ezTheme

Theme provider

To use, wrap your Recipe components in the EzThemeProvider component and pass in the appropriate theme. This is usually done at the app level, but can be nested if needed.

import {EzThemeProvider, EzButton, themes} from  '@ezcater/recipe';

const App = () => (
  <EzThemeProvider theme={themes.ezMarketplaceTheme}>
    <EzButton>Click me</EzButton>
  </EzProvider>
);

Extending themes

We recognize there may be instances where extending a theme is necessary. For example, your app may require context-specific styles that are not supported by Recipe. In these cases, you can create a new customized emotion theme by extending a supported theme.

import {EzThemeProvider, EzButton, themes} from '@ezcater/recipe';

const customTheme = themes.createTheme(themes.ezTheme, {
  // theme overrides here
});

const App = () => (
  <EzThemeProvider theme={customTheme}>
    <EzButton>Click me</EzButton>
  </EzProvider>
);

Note: Recipe's supported themes extend MUI's default theme, which uses the following theme configuration variables: breakpoints, direction, components, palette, spacing, mixins, shadows, typography, transitions, zIndex.

Importing theme properties

import {themes} from '@ezcater/recipe';
import {styled} from '@emotion/react';

const {ezTheme} = themes;

const MyComponent = styled.div`
  color: ${ezTheme.palette.common.primary100};
`;

// Also available as an emotion theme prop

const MyOtherComponent = styled.div`
  color: ${({theme}) => theme.palette.common.primary100};
`;

Including Recipe's supported fonts

To ensure Recipe's fonts are available in a webpage, either self host these fonts, or copy this code into the <head> of your HTML document.

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,100;0,300;0,400;0,700;0,900;1,100;1,300;1,400;1,700;1,900&family=Montserrat:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&family=Roboto+Flex:opsz,wght@8..144,100;8..144,200;8..144,300;8..144,400;8..144,500;8..144,600;8..144,700;8..144,800;8..144,900;8..144,1000&display=swap" rel="stylesheet" />

Development setup

Installation

Recipe is available as an npm package and is used with emotion.

yarn add @ezcater/recipe @emotion/react @emotion/styled

Once everything is installed, you're ready to start importing components!

Server-side rendering (SSR)

If your app uses server-side rendering (SSR), you will need to add some additional configuration to support hydration by passing in the CSS string from stitches using a <style /> tag.

Here's an example of SSR with Next.js:

import React from 'react';
import NextDocument, {Html, Head, Main, NextScript} from 'next/document';
import {stitches} from '@ezcater/recipe';

export default class Document extends NextDocument {
  render() {
    return (
      <Html lang="en">
        <Head>
          <style id="stitches" dangerouslySetInnerHTML={{__html: stitches.getCssText()}} />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

Importing components in your projects

Import the Recipe package, just as you would any other package dependency:

import {EzButton} from '@ezcater/recipe';

export const MyComponent = () => (
  <div>
    <EzButton onClick={() => alert('You clicked me!')}>Click Me!</EzButton>
  </div>
);

Updating to new releases

To install or update to the latest version of Recipe in your application, run the following command:

npm install @ezcater/recipe@latest

or

yarn add @ezcater/recipe@latest

Browser support

We strive for Recipe to have feature parity across all modern browsers.

IE11 is no longer supported as of Recipe v14. For applications that wish to run Recipe v13 or earlier in IE11, polyfills are required for the following browser features:

• Object.entries()
• Element.prototype.closest()
• Element.prototype.scrollTo()
• CSS custom properties
• Array.prototype.findIndex()

We recommend using Polyfill.io in your application to apply necessary polyfills only when they are needed for the requesting browser.

Polyfill.​io Example

<script
  src="https://polyfill.io/v3/polyfill.min.js?features=es2016%2Cdefault%2Ces2017%2Ces2015%2Csmoothscroll"
  type="text/javascript"
>

For IE11 support for CSS custom properties, we recommend also using the css-vars-ponyfill.

Contributing

If you're interested in contributing, check out our contributing guidelines to get started.