vcc-ui

VCC React Component UI Library

This repository contains a collection of React components to be used for developing new customer facing applications at Volvo Car Corporation. You can view the components in action over at our storybook.

Furthermore, if you wish, this library also serves as a toolkit for quickly building your own custom React components.

Why?

• Provide a consistent UX journey for customers and end-users
• Lower the unnecessary cost of design differences and implementation
• Increase developer happiness and productivity

Design Goals

• Allow teams to keep using their existing babel, webpack, parcel, (whatever) tooling/build chain
• Allow for component theming and customization
• Maintain a small footprint, and keep external dependencies to a minimum
• Components should be fully responsive and work on all viewports
• Components should be able to render in server-side, browser & react-native environments
• Components are built with accessibility, performance and SEO best practices in mind
• Components should also be able to render in right to left languages (RTL)
• Provide an interface for i18n and localization.
• Browser support: Internet Explorer 11, Edge 17, Firefox 60, Chrome 66, Safari 11.1, iOS Safari 11.3 and Chrome Android 66.

Basic Usage

Assuming you have a basic React project setup: Install the vcc-ui package via npm or Yarn.

npm install vcc-ui --save

Now wrap your top-level render method in the vcc-ui <StyleProvider> higher order component (HOC). This will inline the CSS required to render the components being used.

import { StyleProvider } from 'vcc-ui'
import App from './app';

ReactDOM.render(
  <StyleProvider><App/></StyleProvider>,
  document.getElementById('root')
);

Now you can start using the components:

import React from 'react';
import { Button } from 'vcc-ui'

export default class App extends React.Component {
  render() {
    return (
      <div>
        <Button withArrow="right">Click me!</Button>
      </div>
    );
  }
}

Assets

While the required CSS is automatically inlined via the <StyleProvider>, assets like images and fonts are not. In order to use them you'll have to symlink (or copy) them from the vcc-ui package into your folder used for serving static files. As an example: For an app created using the create-react-app cli tool, it would look like this:

ln -s ./node_modules/vcc-ui/static ./public/vcc-ui

Components like the <Logo type="square"> will NOT work if you haven't done this.

Fonts

The vcc-ui library has the following Volvo Car branded fonts included in the assets folder

Their names and paths are exposed via the fonts module inside vcc-ui. Use the styleRenderer and loadFonts utility functions provided by vcc-ui:

import { StyleProvider, styleRenderer, loadFonts } from "vcc-ui";

const renderer = styleRenderer();
loadFonts({
    fonts: ["Volvo Novum Light", "Volvo Broad"],
    pathPrefix: "/static/",
    fontDisplay: "block"
  },
  renderer
)

ReactDOM.render(
  <StyleProvider renderer={renderer}><App /></StyleProvider>,
  document.getElementById('root')
);

Components

All components are compatible with the React API and will accept properties like any JSX element: E.g: onClick or id.

In addition, all components have a set of additional properties specific to vcc-ui:

• extend - Object, Customize CSS properties for custom theming/styling of component
• as - String (default: div) Customize what HTML element should be used

Block

A block component is an unstyled <div>, and a starting point for building your own custom component

Example

<Block
  extend={{
    color: 'red',
    background: 'black'
  }}
>
  Hello
</Block>

Inline

An inline component is an unstyled <span>, and a starting point for building your own custom component

Example

<Inline>Hello</Inline>

Button

Properties

• withArrow - String: up, down, or right
• style - String: onDark, onLight (default)

Example

<Button withArrow="right">Hello</Button>

Link

Properties

• withArrow - String: up, down, or right

Example

<Link withArrow="right">Hello</Link>

Icon

Properties

• type - Pick an icon from icons constant
• size - s (12px), m (18px) or l (24px)

Example

<Icon type={icons.search}  />

Arrow

Properties

• direction - String: up, down, left, or right

Example

<Arrow direction="right" />

Logo

Properties

• type - String: square or wordmark

Example

<Logo type="square" />

Nav

Properties

• hideOnScroll - Boolean, default: false
• sticky - Boolean, default: false

Example

<Nav>Hello</Nav>

Constants

ICONS

This module contains references to the icons available in vcc-ui

import { ICONS } from 'vcc-ui'

COLORS

This module contains references to the brand colors available in vcc-ui

import { COLORS } from 'vcc-ui'

MARGINS

This module contains references to the margins in used vcc-ui

import { MARGINS } from 'vcc-ui'

FONTS

This module contains references to the fonts used in vcc-ui

import { FONTS } from 'vcc-ui'

FONT_SIZES

This module contains references to the font-sizes used in vcc-ui

import { FONT_SIZES } from 'vcc-ui'

BREAKPOINTS

import { BREAKPOINTS } from 'vcc-ui'

Breakpoints are currently:

• Small: 420px (mobiles)
• Medium = "768px (touchpads, small laptops)
• Large = "1280px (desktops, large laptops, large touchpads)

Helpers available via BREAKPOINTS:

• untilS - Up until "small" viewports
• fromS - From "small" viewports and up
• untilM - Up until "medium" viewports
• FromL - From "large" viewports and up
• untilL - Up until "large" viewports

example: untilM is equal to @media (max-width: 768px) example: fromL is equal to @media (min-width: 1280px)

Advanced Usage

CSS Toolkit

The styling engine behind vcc-ui is built on top of Fela - A small, high-performnt and framework-agnostic toolbelt to handle state-driven styling in JavaScript.

Media Queries

Use your own, or use the built breakpoints provided by vcc-ui to

import {Block, BREAKPOINTS} from 'vcc-ui'
<Block
  extend={{
    [BREAKPOINTS.untilL]: {
      display: "none"
    },
    [BREAKPOINTS.fromL]: {
      display: "flex",
    }
  }}
>
  Hello
</Block>

Render global styles

You can use the renderer to specify arbitrary CSS or "resets" styles

renderer.renderStatic(
  {
    margin: 0,
    height: "100%",
    fontFamily: "Volvo Sans Light, Arial",
    fontWeight: "normal",
    "-webkit-font-smoothing": "antialiased"
  },
  "body"
);

Server Side Rendering

Depending on what framework you use, the approach will slightly differ.

Render Right To Left (RTL)

For languages like Arabic or Hebrew we need to be able to render components in right to left mode. This can be configured in the renderer AND ConfigContext:

```jsx
import { serverRendered, StyleProvider } from vcc-ui
const renderer = styleRenderer({ isRtl: true});
<StyleProvider renderer={renderer}>
  <ConfigContext.Provider value={{ isRtl: true }}>
    <App />
  </ConfigContext.Provider>
</StyleProvider>

You also need to set <body dir="rtl"> in your HTML template.

Example of SSR in react-static:

import { getStyles, serverRendered, StyleProvider } from vcc-ui

renderToHtml: (render, Comp, meta) => {
  const serverRenderer = styleRenderer();
  const html = render(
    <StyleProvider renderer={serverRenderer}>
      <Comp />
    </StyleProvider>
  );
  meta.styleTags = getStyles(serverRenderer).map(({ media, css }) => (
    <style dangerouslySetInnerHTML={{ __html: css }} media={media} />
  ));
  return html;
},

Utility functions

StyleProvider

A HOC that provides CSS styling context to all child components

ConfigContext

Provide additional config for the vcc-ui components.

Properties

value (object)

• pathPrefix: prefix static asset paths if you are serving assets like images from a different domain or public path

Example

<StyleProvider renderer={renderer}>
  <ConfigContext.Provider value={{ pathPrefix: "https://cdn.volvocars.com/" }}>
    <App />
  </ConfigContext.Provider>
</StyleProvider>

styleRenderer

The rendering engine that can be customized and passed to the style provider

getstyles

Get the styles that was generated for a render, useful for when sending server side generated styles to client

loadFonts

Will load a given list of fonts by injecting @font-face declarations