# @clds/blender

> Utility to blend design system colors

Latest version **0.70.2** (published 2025-07-21) · 0 weekly downloads

## Install

```sh
npm install @clds/blender
pnpm add @clds/blender
yarn add @clds/blender
bun add @clds/blender
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.70.2 |
| Published | 2025-07-21 |
| First published | 2022-06-30 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 84.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cloudinary |
| Maintainers | cloudinary-internal |

## Links

- npm: https://www.npmjs.com/package/@clds/blender
- Repository: https://github.com/cloudinary/design-system
- Homepage: https://github.com/cloudinary/design-system/tree/main/libs/foundations/blender#readme
- Issues: https://github.com/cloudinary/design-system/issues
- npm.io page: https://npm.io/package/@clds/blender

## Dependencies (5)

- [polished](https://npm.io/package/polished.md) 3.7.2
- [color-blend](https://npm.io/package/color-blend.md) 4.0.0
- [@clds/themes](https://npm.io/package/@clds/themes.md) 0.70.2
- [@clds/typography](https://npm.io/package/@clds/typography.md) 0.70.2
- [@clds/common-definitions](https://npm.io/package/@clds/common-definitions.md) 0.70.2

## Recent versions

- 0.70.2 (latest) — 2025-07-21
- 0.70.1 — 2025-07-08
- 0.70.0 — 2025-07-06
- 0.69.0 — 2025-06-26
- 0.68.0 — 2025-06-24
- 0.67.1 — 2025-06-12
- 0.67.0 — 2025-06-12
- 0.66.0 — 2025-06-09
- 0.65.0 — 2025-06-08
- 0.64.2 — 2025-06-05
- 0.64.1 — 2025-06-03
- 0.64.0 — 2025-06-03
- 0.63.1 — 2025-05-25
- 0.63.0 — 2025-05-06
- 0.62.4 — 2025-04-09
- … 156 more at https://npm.io/package/@clds/blender/versions

## README

## @clds/blender

---

[![npm version](https://img.shields.io/npm/v/@clds/blender)](https://www.npmjs.org/package/@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:

```jsx
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.

```tsx
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>
);
```

## Versioning

This library follows [Semantic Versioning](http://semver.org/).

## License

See [LICENSE](https://github.com/cloudinary/design-system/blob/main/LICENSE)

---
_Source: https://npm.io/package/@clds/blender · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._