@teamleader/ahoy

Ahoy!

Ahoy is a set of React components that implement the Teamleader design specification.

Installation

Ahoy can be installed as an npm package:

$ npm install --save @teamleader/ahoy

or

$ yarn install @teamleader/ahoy

Basic usage

In this minimal example, we import a Button with styles already bundled:

import React from 'react';
import ReactDOM from 'react-dom';
import { Button } from '@teamleader/ahoy';

ReactDOM.render(<Button label="Hello World!" />, document.getElementById('app'));

Import the CSS into your project via JS or CSS.

JS

import '@teamleader/ahoy/es/index.css';

or CSS

@import url('@teamleader/ahoy/es/index.css');

AhoyProvider

Ahoy provides a AhoyProvider component that you can use to wrap your application and pass a global config to Ahoy. This is optional.

const config = useMemo(
  () => ({
    currencies,
    translate,
  }),
  [currencies, translate],
);

<AhoyProvider config={config}>
  <Heading1>Hello World!</Heading1>
</AhoyProvider>;

You can pass the following properties to the AhoyProvider config:

currencies (optional)

An array of currencies (with a config), that will be used to format money values when using the MoneyDisplay component. Example:

<AhoyProvider
  config={{
    currencies: [
      {
        code: 'EUR',
        decimalScale: 2,
        separator: { decimal: ',', thousands: '.' },
        symbol: '€',
        symbolPosition: 'before',
      },
    ],
  }}
>
  {children}
</AhoyProvider>

translate (optional)

A function that is used so that components can use translated strings. It received a key (string) as parameter, and should return a string or null. When translate is not provided or it returns null, the default english translation will be used.

<AhoyProvider
  config={{
    translate: (key: string) => {
      // use the translate function from your application, e.g. from react-i18next
      return i18n.translate(key);
    }
  }}
>
  {children}
</AhoyProvider>

Colors

The colors of the Ahoy system are:

• aqua
• gold
• neutral
• mint
• ruby
• teal
• violet

For each color there are 5 tints.

• lightest
• light
• normal
• dark
• darkest

CSS

The available color variables are

--color-aqua-lightest
--color-aqua-light
--color-aqua
--color-aqua-dark
--color-aqua-darkest
--color-gold-lightest
--color-gold-light
--color-gold
--color-gold-dark
--color-gold-darkest
--color-neutral-lightest
--color-neutral-light
--color-neutral
--color-neutral-dark
--color-neutral-darkest
--color-mint-lightest
--color-mint-light
--color-mint
--color-mint-dark
--color-mint-darkest
--color-ruby-lightest
--color-ruby-light
--color-ruby
--color-ruby-dark
--color-ruby-darkest
--color-teal-lightest
--color-teal-light
--color-teal
--color-teal-dark
--color-teal-darkest
--color-violet-lightest
--color-violet-light
--color-violet
--color-violet-dark
--color-violet-darkest
--color-black
--color-white

The colors are defined as hsl values. For each color the h, s an l value are also available as separate variables. There is also a variable that has the hsl values combined. This way you can do color calculations on them with native css (instead of using postcss-color plugin for example). Some examples:

lighten(12%)

hsl(var(--color-ruby-hsl-h), var(--color-ruby-hsl-s), calc(var(--color-ruby-hsl-l) - 12%))

tint(64%)

hsl(var(--color-ruby-h), var(--color-ruby-s), calc(var(--color-ruby-l) * 1.64))

alpha(12%)

hsl(var(--color-ruby-hsl) / 12%)

JavaScript

import { COLOR, COLORS, TINTS, colorsWithout, tintsWithout } from '@teamleader/ahoy';

COLOR: an object that contains the colors as hex values (e.g. COLOR.MINT.DARKEST).

COLORS: an array with the color names (['aqua', 'gold', 'neutral', 'mint', 'ruby', 'teal', 'violet']).

TINTS: an array with the tint names (['lightest', 'light', 'normal', 'dark', 'darkest']).

colorsWithout: a function to get an array of colors without a given array of colors (colorsWithout(['neutral', 'violet]))

tintsWithout: a function to get an array of tints without a given array of tints (tintsWithout(['light', 'lightest]))

Browser support

This library officially supports the last two versions of the major browsers. This is mainly because of dependencies and ease of mind.

• Luxon browser support

License

This project is licensed under the terms of the MIT license.