Qantas Hotels' library of accessible React components and assets.

To see what’s available, check out roo-ui's storybook. If you want to jump in and and play around with the project check out Roo UI playground - it’s setup so you can start using it straight away.

Contents

• About the project
• Installation
• FAQs
• Helpful resources
• Contributing

About the project

Roo UI is built with Emotion which is a CSS-in-JS library. We use Styled System which allows us to pass props which style components. These props reference values from the theme. Alongside these tools we use Polished for CSS helper functions.

When using emotion, sometimes unwanted props make their way through to the DOM. React will throw a warning asking if you meant to add this attribute. To get around this we are using a function called omitProps. Using this, we can supply an omit array argument which prevents specified props from making there way to the DOM.

Supported devices

We support the latest two versions of modern web browsers and IE11+.

Accessibility

Being under the Qantas umbrella we are required to meet AA compliance.

Installation

Roo UI is available as a package on npm, and can be installed with Yarn or npm:

$ yarn add roo-ui

Peer dependencies

While we aim to keep the library unopinionated there are a few peer dependencies which are required.

Install peer dependencies with Yarn or npm:

$ yarn add react react-dom prop-types enzyme @emotion/core @emotion/styled styled-system@^4.1.0

Setup

Theme provider

In the root of your app, render a <ThemeProvider />, and pass it a theme:

import { ThemeProvider, theme } from 'roo-ui';

export default (
  <ThemeProvider theme={theme}>
    <App />
  </ThemeProvider>
);

Theming

To have consistent styles between our apps we should aim to use the default theme styles.

You can override theme values by importing the roo-ui theme and using a function such as Lodash’s merge to combine it with your own theme object.

Fonts

Import the appropriate font for your theme:

import 'roo-ui/fonts/ciutadella.css';

Icons

SVG icon paths are accessed from your app's theme (theme.icons[iconName].path).

A default set of icons are included in the base theme.

To add more icons, import them from roo-ui/icons and include them in your apps theme.

Example: Add more icons to your app's theme

// my-app/icons.js
export { arrowUpward, arrowForward } from 'roo-ui/icons';

// my-app/theme.js
import * as icons from './icons';

export default {
  ...qantas,
  icons: {
    ...qantas.icons,
    ...icons,
  },
};

You can also add icon components from third party libraries like react-icons/md in your app's theme.

Example: Add icon components to your app's theme

// my-app/theme.js
import { MdCheckCircleOutline } from 'react-icons/md';

export default {
  ...qantas,
  icons: {
    ...qantas.icons,
    MdCheckCircleOutline,
  },
};

CSS reset

We recommend using normalize.css.

Install normalize.css and import it to normalize default browser styles:

yarn add normalize.css

import 'normalize.css/normalize.css';

Bundler requirements

If your project is setup with Create React App you can skip this step.

If you're using Webpack, you'll need to setup file loader, style loader and CSS loader.

FAQ’s

• Contents
• About the project
  • Supported devices
  • Accessibility
• Installation
  • Peer dependencies
• Setup
  • Theme provider
  • Theming
  • Fonts
  • Icons
  • CSS reset
  • Bundler requirements
• FAQ’s
  • How do I do layout in this new world?
  • How do I do responsive styles?
  • How do I change the font size?
  • How do I add spacing to elements?
  • What’s a good usage example?
  • How do I use the theme?
  • How can I get help?
  • Can I contribute?
• Helpful resources
  • General
  • Accessibility

How do I do layout in this new world?

You’ll most likely need to use these three components: Container, Box and Flex.

Container will define your max width, use Box the same way you would div and think of Flex as a div with display: flex on it.

How do I do responsive styles?

In your app you can use media queries as you would have in the past.

We also provide a Hide component which you can wrap around components you would like to hide. It accepts props to hide its children at different screen sizes.

How do I change the font size?

In the theme you’ll see text styles defined. With styled system you can add textStyle prop to with the key as the value to text components such as Text and Paragraph.

<Paragraph textStyle=”caps”>Hello world.</Paragraph/>

How do I add spacing to elements?

The theme is setup to use a 4px grid under the space key. Where space.0 is 0px and space.1 is 4px. A easy way to work out the number you need is to take it and divide it by 4.

What’s a good usage example?

StarRating, Modal and DatePicker are good examples of composing components together.

How do I use the theme?

Depending on what you're trying to do you can access the theme in three ways.

When you're wanting to tweak a component, you can pass through props that are defined via the Styled System API.

If you're writing CSS-in-JS and want to access theme values you can use styled systems themeGet. It allows you to get values out of the theme.

Alternatively, you can import the theme directly into your component.

How can I get help?

There's a few different ways. Chat to any of the contributors, pop a question in the #roo-ui slack channel or attend a Roo UI working group.

Can I contribute?

Yes, refer to CONTRIBUTING.md for instructions. Browse the issues and pick one up or send a pull request for a new component or asset.

Helpful resources

General

• Styled System API table reference
• Theme

Accessibility

• Accessibility audit Chrome extension
• A11Y project
• MDN accessibility docs
• Accessible UI components for the web article