vcc-ui

VCC React Component UI Library

This repository contains a collection of React components used for developing new customer facing applications at Volvo Car Corporation.

Furthermore, this library also exposes it's internal toolkit to enable you to build own custom React components using the same patterns.

You can view the components in action over at our storybook.

In this README

• Why vcc-ui?
• Design Goals
• Contributing
• Browser Support
• Basic Usage
• Components
• Advanced Usage
• Utility Functions

Why vcc-ui

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

Design Goals

• Allow teams to keep using their existing tooling/build chain (babel, webpack, parcel, [insert new tech here])
• Maintain a small footprint, and keep external dependencies to a minimum
• Components should be fully responsive and work on all supported viewports/devices
• 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.

Contributing

Please read the CONTRIBUTING.md document for more information on how to contribute to vcc-ui

Browser support

• Internet Explorer 11, Edge 17
• Safari 11.1, iOS Safari 11.3
• Firefox 60
• Chrome 66
• 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 { Block, CTA } from 'vcc-ui'

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

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 or HTML element: E.g: onClick or id.

Block

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

Properties

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

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 inline component

Properties

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

Example

<Inline>Hello</Inline>

CTA

Properties

• withArrow - String: up, down, or right (false - default)
• style - String: onDark, onLight (onLight - default)
• secondary: Boolean: apply secondary button styles (false - default)

Example

<CTA secondary style="onDark" withArrow="right">Hello</CTA>

Click

An unstyled component that can be used for creating your own clickable components. It's basically a native HTML button element with all the browser default styling removed. Read more about (buttons and accessbility)[https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role]

Properties

• extend - Object: Customize CSS properties for custom theming/styling of component (none - default)

Example

<Click>I'm an unstyled clickable button</Click>

Link

Properties

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

Example

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

Icon

Properties

• type - Pick an icon from icons constant (account, search, facebook, twitter, youtube, linkedin, instagram, globe)
• 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 (square - default)

Example

<Logo type="square" />

Nav

Properties

• hideOnScroll - Boolean, (false - default)
• sticky - Boolean, (false - default)

Example

<Nav>Hello</Nav>

NavItem

Properties

• dropdown - Boolean, (false - default)
• isACtive - Boolean, (false - default)

Example

<NavItem dropdown isActive>Hello</NavItem>

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-performant 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 "reset" 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. Check out the examples folder to get an idea how this can is achieved.

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;
},

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:

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.

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
• isRtl: render the components in right-to-left mode

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