# @clds/design-system-foundations

> ---

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

## Install

```sh
npm install @clds/design-system-foundations
pnpm add @clds/design-system-foundations
yarn add @clds/design-system-foundations
bun add @clds/design-system-foundations
```

## 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 | 1 |
| Unpacked size | 107.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cloudinary |
| Maintainers | cloudinary-internal |

## Links

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

## Dependencies (1)

- [@clds/themes](https://npm.io/package/@clds/themes.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/design-system-foundations/versions

## README

## @clds/design-system-foundations

---

[![npm version](https://img.shields.io/npm/v/@clds/design-system-foundations)](https://www.npmjs.org/package/@clds/design-system-foundations)

Design System Foundations establish two abstract concepts:

- Size
- Surface

## Size

When some component can contain other inside, it usually creates a slot for it, sometimes called "area".
For example, the button can contain the icon.

In order to make implementations of all components decoupled, we introduce a concept that describes
how much space child component is expected to consume.

It is expressed in an abstract unit, which is equal to theme spacing units: xxs, sm, md, etc.

We create components that can automatically adjust it's size if the component hasn't specified
size directly.

The communication between containers and children is done via special `FoundationContext`.

Once component puts the expected size into the context, then any component inside can read it and default it's
size to make sure it consumes the space expected by the container.

### Size mapping

Components size props are not standardized.
For example `sm` button doesn't have `spacing.sm` height but greater. Also, button supports only `sm` and `md` sizes.
We should map context props into components props individually.

## Surface

Components can have different color versions.
The thing, which is common for many components, is their `tone` and `variant`.
Variant implies the main color for the component theme (`primary`, `error`, `etc`),
and `tone` implies how colors are used (subtle - lightweight, non eye-disturbing, solid - intense colors, bring user attention).
The surface is an abstract concept that combines both `tone` and `variant`.

Many components in design system accept properties which are superset of the `surface` concept.
But when one component is used inside the other, it is expected that the child component will somehow adjust own surface to be clearly visible when inside the container.

This is why we share this information about container surface via `SurfaceContext`.
It means that if the component doesn't have own surface-related props specified, they will default to
ones mapped from the `Surface` context.

### Surface mapping

Child surface-related default props are mapped from the surface context,
which means that the child component has to decide how to create own default style to make it visible on the surface.

For example, if `Banner` component is used with `success` variant, it will put
`{ tone: 'solid', variant: 'success' }` into the context.

If you put a `Chip` inside a banner, it reads the context and defaults its own `variant` to `success`
but the button `tone`, to be clearly visible, has to be the opposite - `solid` when `subtle` and `subtle` when `solid`.

# API

This package contains API for two independent contexts.

- foundation context - `FoundationContextProvider` and `createUseFoundationHook`
- surface context - `SurfaceContextProvider` and `createUseSurfaceHook`

You can find more information about them in JSDocs.

## 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/design-system-foundations · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._