@clds/component-theme

This package introduces fully typed, object-oriented theming api to consume directly in your styled components.

If you consume a package which uses it, all you need is to provide correct global theme using <ThemeProvider> from 'styled-components'.
You can override such component in your application using override utility.
You don't need any extra setup and plugins!

This api provides smart intellisense and autocompletion features for all mixins and component definition also preserving type of original theme value.

Global theme mixins

This package exposes styled component mixins for global theme variables.

import { globalTheme } from '@clds/component-theme';

const Button = styled.div`
  color: ${globalTheme.palette.primary};
`;

Component themes

The component shouldn't itself refer to global theme directly.
Instead, it should have created a separate component theme using createTheme api.
It introduces more semantic definitions and contain mappings to global theme.

import { globalTheme, createTheme } from '@clds/component-theme';

export const buttonTheme = createTheme({
  border: { radius: globalTheme.spacing.lg },
  shadow: globalTheme.shadow.sm,
  text: { color: globalTheme.palette.contrastHigh },
  onState: {
    padding: globalTheme.spacing.lg,
    background: { color: globalTheme.palette.surface },
  },
  offState: {
    padding: globalTheme.spacing.sm,
    background: { color: globalTheme.palette.primary },
  },
});

import buttonTheme from './myTheme';

const Button = styled.div`
  color: ${buttonTheme.palette.primary};
  background: ${buttonTheme.background.color};
`;

Mixin tree

You can use mixins that were automatically created for each single global theme node, including root, all parents and leaves
It refers to both leaves (theme values) or nodes (theme branches).
Mixins were also created for each definition node of component theme definition.

import { mix } from 'polished';
import { combineValues, globalTheme, propsMixin } from '@clds/component-theme';
import { buttonTheme } from './myTheme';

const Button = styled.div`
  color: ${combineValues(
    globalTheme.palette,
    propsMixin,
    (palette, props) => palette[props.variant],
  )};
  background-color: ${combineValues(
    buttonTheme.mixValue,
    buttonTheme.variants,
    globalTheme.palette.error,
    propsMixin,
    (mixValue, buttonVariants, errorColor, props) =>
      mix(mixValue, buttonVariants[props.variant].text.color, errorColor),
  )};
`;

Optimizations

Mixins created for parent theme nodes may cause cost calculation every render.
They need to combine theme defaults with current overrides found in theme context.

To solve this, mixins are optimized. Every mixin tree is precompiled and cached until theme provider updates with new theme value.

Tutorial

You can follow tutorial in storybook to see detailed usage and capabilities.

Versioning

This library follows Semantic Versioning.

License

See LICENSE

@clds/component-theme