@biom3/react

@biom3/react

This package publishes via CICD to the public npm component: @biom3/react.

What's inside?

All react based BIOME components, hooks and utils. All components and hooks will be atleast 90% covered with tests. To read more about our API philosophy see this document.

How to use

To use any @biom3/react primitives, simply install the package using your package manager of choice. For example:

npm i @biom3/react

and then import the primitive you need (all primitives will be exported from the root of the package):

import { Box, IconArrowBackward } from '@biom3/react';

Using sx to style BIOME react components

All BIOME react components provide the same API which can be used for making various style changes to a component and it's children. sx supports any style that you can render using @emotion/react.

As well as this, sx also supports various shorthand properties. A full listing of all supported shorthand properties (and their longhand equivalents) can be found here. It's completely up to the consumer as to whether they use standard longhand css properties (which might be more friendly to a junior engineer's eyes), or the time-saving shorthand properties.

Furthermore, any sx style property, can be submitted as either a string, a function which returns a string, an array, or an object.

sx Nesting

For now, nesting inside sx will only allow up to 1 level of nesting. This means that when you are composing custom sx styles, you will need to write them like:

<Button
  sx={{
    background: 'base.gradient.3',
    span: { color: 'base.color.brand.1' },
    '&:hover': {
      background: 'transparent',
      boxShadow: 'inset 0 0 0 5px rgba(0,0,0,0.1)',
    },
    '&:hover span': {
      color: 'base.color.brand.2',
    },
    '&:hover::before': {
      backgroundImage: 'base.gradient.3',
    },
  }}
>
  button text
</Button>

as opposed to:

<Button
  sx={{
    background: 'base.gradient.3',
    span: { color: 'base.color.brand.1' },
    '&:hover': {
      background: 'transparent',
      boxShadow: 'inset 0 0 0 5px rgba(0,0,0,0.1)',
      '& span': {
        color: 'base.color.brand.2',
      },
      '&::before': {
        backgroundImage: 'base.gradient.3',
      },
    },
  }}
>
  button text
</Button>

Responsive sx props

Using array and object syntax will grant you easy access to responsive styles, according to your theme's base.breakpoint tokens. For exmaple:

// Both of these snippets of code will render a div that has:
// 1. default blue background-color
// 2. red background-color at the "small" breakpoint and above
// 3. green background-color at the "medium" breakpoint and above
// 4. yellow background-color at the "large" breakpoint and above
// 5. gold background-color at the "xLarge" breakpoint and above
// 6. rebeccapurple background-color at the "xxLarge" breakpoint and above
<Box
  sx={{ bgc: ["blue", "red", "green", "yellow", "gold", "rebeccapurple"] }}
/>
// or
<Box
  sx={{
    bgc: {
      default: "blue", small: "red", medium: "green", large: "yellow", xLarge: "gold", xxLarge: "rebeccapurple"
    }
  }}
/>

*NOTE: You can skip breakpoints by using null, or simply by leaving them out. For example:

// Both of these snippets of code will render a div that has:
// 1. default blue background-color
// 2. red background-color at the "small" breakpoint and above
// 3. rebeccapurple background-color at the "xxLarge" breakpoint and above
<Box
  sx={{ bgc: ["blue", "red", null, null, null, "rebeccapurple"] }}
/>
// or
<Box
  sx={{
    bgc: { default: "blue", small: "red", xxLarge: "rebeccapurple" }
  }}
/>
// or
<Box
  sx={{
    bgc: { default: "blue", small: "red", medium: null, xxLarge: "rebeccapurple" }
  }}
/>

Building compound sx rules

When passing a function, that function will always be called by passing in BIOME's theme, as the first arguement. For example:

import { Theme } from '@emotion/react';
<Box
  sx={{
    padding: (theme: Theme) =>
      `${theme.base.spacing.x2} ${theme.base.spacing.x5}`,
  }}
/>;

Component maturity status

We have designed and implemented a grqanular status system where each BIOME design system component has it's own maturity status. Information on these component statuses can be found in confluence.

Each status update should be accompanied by a timestamp (format: ddd mm yyyy, eg: '2nd Dec 2022'). We will use these timestamps to move components through the status levels, as technical debt. You can find each component's status, inside of it's readme.md file.

Component statuses

! alpha !

Early on in a component’s life, it’s status should be set to alpha - which gives developers using it, an indication of the component's maturity. alpha components are likely to see API changes (breaking changes will of-course be avoided - but may sometimes be necessary).

@@ beta @@

Components become beta when they have been used in production at least once.

+ stable +

Components will become stable when they have been beta for 2 months with no API changes. Stable components are fully mature, and will not have their API’s change in a breaking way (unless a new major version is released).

How to provide design-tokens to all BIOME components

BIOME react components are all theme-aware. This means that they all need to sit underneath the <BiomeThemeProvider />. Please ensure you wrap your whole application in the BiomeThemeProvider, so that components at all levels in the tree, have access to BIOME design tokens.

For more information on the BiomeThemeProvider, please view it's readme file.

NextJS dependence

You may notice that this package contains some nextjs config files / settings. @biom3/react has a small dependence on NextJS, but only for it's next/link types.

Next is also used for internal test build tooling, mostly because its so easy to do so inside of TurboRepo (and has some minor speed benefits).