@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.

License

See LICENSE