Polarwind

Polarwind is a React component library for the Envoy design system.

App development

Using the React components

While we do offer a CSS-only version, we strongly recommend using the React versions of our components. It allows for rich, complex components like Tabs and autogrowing multline TextFields, and will not have as many breaking changes as the CSS-only version.

Installation

Run the following command using npm:

npm install @envoy/polarwind --save

If you prefer Yarn, use the following command instead:

yarn add @envoy/polarwind

Usage

1. Import the CSS directly into your project if your asset packager supports it:

import "@envoy/polarwind/polarwind.css";

Otherwise include the CSS in your HTML. We suggest copying the styles file into your own project, but you may also use it directly:

<link
  rel="stylesheet"
  href="https://unpkg.com/@envoy/[email protected]/polarwind.css"
/>

2. Include any of the provided components in your project:

import { AppProvider, Page, Button } from "@envoy/polarwind";

3. Tell React to render the element in the DOM:

ReactDOM.render(
  <AppProvider>
    <Page title="Example app">
      <Button onClick={() => alert("Button clicked!")}>Example button</Button>
    </Page>
  </AppProvider>,
  document.querySelector("#app")
);

Using the CSS components

If React doesn't make sense for your application, you can use a CSS-only version of our components. This includes all the styles you need for every component in the library, but you'll be responsible for writing the correct markup and updating classes and DOM attributes in response to user events.

Usage

1. Include the CSS in your HTML. We suggest copying the styles file into your own project, but you may also use it directly:

<link
  rel="stylesheet"
  href="https://unpkg.com/@envoy/[email protected]/polarwind.css"
/>

2. Include the markup and associated classes in your HTML document:

<button class="Polarwind-Button">Example button</button>

Examples

We have created example applications to document some of the ways you could include Polarwind in one of your own applications. Each of these examples includes further documentation on how to install dependencies and run the app:

• create-react-app example

Development

This package has a development dependency on a private @envoy/tailwind package hosted on GitHub Packages. It contains the common Envoy shared preset for Tailwind. You will need to perform an npm login against the @envoy scope for you to be able to install the package (yes, even if this project uses yarn you still need to use npm for logging in)

$ npm login --scope envoy --registry=https://npm.pkg.github.com
Username: <your github username>
Password: <your personal access token with scopes `repo` and `read:packages`>
Email: <your envoy email>

You will have to generate a Personal Access Token (PAT) with the scopes repo and read:packages in order to log in. Now you should be able to yarn install as normal.

GitHub Actions in this project will use a PAT from envoybot.

We use Storybook to create a simple, hot-reloading playground for development on these components. Run yarn start in order to start the Storybook server.

We use generators to build scaffolding for a typical component. Run yarn generate to see the list of generators provided.

Visual regression testing

Chromatic runs for every pull request. Chromatic is a tool that compares screenshots for every single component we have in the library.

Chromatic is not always 100% accurate. Since it uses screenshot comparison, even browser sub-pixel rendering differences can cause Chromatic to ask for user confirmation of whether a change was intended or not. In cases like that, use your best judgement to determine whether you need to address it or not. This is why the choice to approve something or not is always manual. While everyone can view changes, only members of the Envoy team an approve changes.

Manual visual regression testing

To start a server for manually viewing the visual regression testing examples, run yarn storybook.

Learning resources

If you're new to React, we recommend you start with the official React Getting Started documentation. As you read through the topics we suggest you follow along using their React Hello World CodePen example.

Additional resources:

• Online training courses at reacttraining.com, buildwithreact.com, and reactforbeginners.com.
• The community resources in Awesome React.
• As questions and find answers in the various React support communities.

License

Source code is under a custom license based on MIT. The license restricts Polarwind usage to applications that integrate or interoperate with Envoy software or services, with additional restrictions for external, stand-alone applications.

Trivia

Polarwind is a portmanteau of Polaris and Tailwind CSS.