README

psammead-styles -

This package provides a collection of string constants for use in CSS, containing non-GEL styling details that are bespoke to specific BBC services and products

Exports

/colours - Project-defined colours that will be required by multiple Psammead components or themes. These colours are not defined by GEL. /detection - Project-defined CSS feature detection statements. /fonts - Project-defined browser behaviours for the Reith font. The primary reason these are not considered GEL-defined (and not part of @bbc/gel-foundations) is due to the custom weighting and loading definitions. More details on the font-faces defined in this package are available here.. Also includes declarations for all World Service fonts.

/font-styles provides functions that can be used to get font-styles for different services. If a font-style is not available all the functions will fallback to regular sans font-style of the service.

/global-styles Provides project-defined global styles defined using styled-normalize and box sizing.

Installation

npm install @bbc/psammead-styles --save

Usage

import { C_POSTBOX } from '@bbc/psammead-styles/colours';

import { F_REITH_SANS_REGULAR, F_REITH_SANS_ITALIC } from '@bbc/psammead-styles/fonts';

By importing a subset of the font-face definitions defined in this package, you can prioritise only the most commonly needed fonts for your project, with browser styling stepping in for less common scenarios. For example, in these examples, which import custom fonts for only Reith Sans Regular and Italic, any bold styling would be "faked" by the browser.

You will likely want to use these font-face definitions in tandem with the GEL-defined font stack definitions, which are available in @bbc/gel-foundations:

import { GEL_FF_REITH_SANS } from '@bbc/gel-foundations/typography';

These values can then be used directly within CSS declarations in code. Note that font-faces should only be declared once on a page:

import { css } from 'styled-components';

// These should only be included on your page once.
const someGlobalCSS = css`
  ${F_REITH_SANS_REGULAR};
  ${F_REITH_SANS_ITALIC};
`;

const SomeStyledComponent = css`
  background-color: ${C_POSTBOX};
  font-family: ${GEL_FF_REITH_SANS};
`;

font-styles

In case you are using embedded fonts, you need to make sure you have loaded your fonts first before using the functions. If the embedded font is not loaded, the fallback font will be applied

import { getSansRegular } from '@bbc/psammead-styles/font-styles';

const fontStyle = getSansRegular('news');

const SomeStyledComponent = css`
  ${fontStyle};
  /* more css styles */
`;

detection

We have defined custom feature detection statements (using CSS @supports syntax) to provide workarounds for browser-specific bugs.

grid: We experienced issues using @supports (display:grid) from browsers with buggy CSS Grid implementations, and found that detecting on @supports (grid-template-columns: fit-content(200px)) gave more consistent detection.

import { grid } from '@bbc/psammead-styles/detection';

const someGridUsingComponent = css`
  @supports (${grid}) {
    display: grid;
    /* grid CSS */
  }

  /* fallback CSS */
`;

global-styles

We export a global styles component which uses styled-normalize and defines css rules for box-sizing. This component accepts an optional fonts prop which is an array of font styles to be applied in the global styles.

import GlobalStyles from '@bbc/psammead-styles/global-styles';
import {
  F_REITH_SANS_REGULAR,
  F_REITH_SERIF_MEDIUM,
} from '@bbc/psammead-styles/fonts';

<GlobalStyles fonts={[
      F_REITH_SANS_REGULAR,
      F_REITH_SERIF_MEDIUM,
    ]}
/>

Contributing

When adding a new export to this utility package the export tests also need to be updated. When removing an exisiting export from this utility package the export tests need to be updated and the package version requires a major change (EG: 1.2.1 -> 2.0.0) as this would be considered a breaking change due to functionality being removed.

Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead respository.

Code of Conduct

We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.

License

Psammead is Apache 2.0 licensed.

Usage no npm install needed!