@clds/blender NPM

@clds/blender

This is Cloudinary Design System color blending tool.

In Cloudinary Design System, we explicitly define styles of any surface. A surface consists of background color, foreground color, and typography type.

If you implement some design, and you can't decide which defined surface style to use, probably we have design issue where not allowed mix of foreground, background and typography was used.

This tool allows you to generate valid colors and typography for all existing derived states for all design system components.

Base colors come from palette (primary, secondary, surface, ...) but we allow to mix them using special restricting rules.

Input parameters you can put into the blender:

blend variant - the color name from palette which implies the color theme (error, warning, primary...)
blend mode, where you define how background and foreground are mixed together
- plainSolid - no background, solid foreground (same as variant)
- plainContrast - no background, contrastHigh foreground
- surfaceSolid - surface background, solid foreground (same as variant)
- surfaceContrast - surface background, contrastHigh foreground
- solidContrast - solid background (same as variant), contrastInvert foreground (contrasting to solid background)
blend intensity, which imitates interaction states - designers decide how to map state to the intensity individually per component
- sm - ie. for button it is used for hover states
- md - ie. for button it is used usually for normal states
- lg - ie. for button it is used usually for selected states
- xl - ie. for button it is used usually for hover+selected states

Output parameters you get from the blender:

background color
foreground color
typography type

Blending rule

Single component's surface should be build using only methods from blender. In case of plain backgrounds (plainSolid, plainContrast) we shouldn't use them to create layers inside component. This means specifically, that we can't create two overlaying div elements with plain background to achieve new surface. However, two independent components could be used in the way, where plain surface of one component overlays the other one. For example: subtle alert (surfaceSolid, sm) can consist of plain button in hover state (plainSolid, sm), creating new surface which is not achievable from blender.

API

blenderBackground()

Styled component mixin you can use for background colors in your blender-supporting component.

blenderForeground()

Styled component mixin you can use for foreground colors in your blender-supporting component.

getBlenderTypographyType()

function that returns you proper typography type for your state.

Usage

Easiest way to consume blender is to create styled components and use getBlenderTypographyType together with <Typography/> component:

import {
  blenderBackground,
  blenderForeground,
  getBlenderTypographyType,
} from '@clds/blender';
// other imports

const Root = styled.div`
  background-color: ${blenderBackground};
`;

const Icon = styled.svg`
  fill: ${blenderForeground};
`;

const Example = (props) => (
  <Root {...props}>
    <Icon {...props} path="..." />
    <Typography
      as="span"
      size="sm"
      type={getBlenderTypographyType(props.mode, props.variant)}
    >
      This is just the demo
    </Typography>
  </Root>
);

Example.defaultProps = {
  variant: 'error',
  mode: 'plainSolid',
  intensity: 'lg',
};

blenderCss

This an accompanying solution that allows to communicate about blender surface through CSS variables.

populateVariables()

Creates a styled mixin that will provide all necessary blender variables based on blender props passed as an argument.

backgroundFromCssVariables

Styled mixin that reads blender background from CSS variable

foregroundFromCssVariables

Styled mixin that reads blender foreground from CSS variable

typographyFromCssVariables()

Creates styled mixin that, for specific typography size, defines all typography-related properties from CSS variables.

Example

This is an example of creating a surface that establishes blender css variables based on pseudo selectors.

import styled from 'styled-components';
import { blenderCss } from '@clds/blender';

const Button = styled.button`
  ${blenderCss.populateVariables({
    mode: 'plainContrast',
    variant: 'primary',
    intensity: 'md',
  })};

  &:hover,
  &:focus-visible {
    ${blenderCss.populateVariables({
      mode: 'solidContrast',
      variant: 'primary',
      intensity: 'lg',
    })};
  }

  &:active {
    ${blenderCss.populateVariables({
      mode: 'solidContrast',
      variant: 'primary',
      intensity: 'xl',
    })};
  }

  background-color: ${blenderCss.backgroundFromCssVariables};
  border: 1px solid ${blenderCss.borderColorFromCssVariables};
`;

const LogoIcon = styled.div`
  background: ${blenderCss.foregroundFromCssVariables};
`;

const Text = styled.p`
  ${blenderCss.typographyFromCssVariables('xs')};
`;

export const Example = () => (
  <Button>
    <LogoIcon />
    <Text>Hello</Text>
  </Button>
);