Component Variables

# Overview

Component variables provide a versioned method for teams to:

  • Import the exact CSS styles used in the Cedar Vue component
  • Apply these exact CSS styles to elements in their project

Component variables are only available for a core subset of Cedar components, and are distributed in SCSS and LESS format.

Component variables include mixins such as @include cdr-button-base-mixin which sets many properties on an element. Each component has a base mixin which sets properties that apply to all components of that type, as well as modifier mixins which only apply to a specific variant of that component

For example, you can import the styling for a Cedar primary button component using a mixin:

.your-button-component {
  @include cdr-button-base-mixin;
  @include cdr-button-primary-mixin;
}
1
2
3
4

# Contract of Intent

Versioning

  • Component variables are a versioned export of the exact CSS styles being used in the Cedar Vue components
  • Whenever a major version of Cedar is released, a corresponding major version of component variables will also be published
  • For minor or patch versions of Cedar, component variables will only be published if there were changes made to the distributed files
  • Outside of the Cedar release schedule, patch versions of component variables will only be issued if a bug is found in the distribution

Semantic naming

  • Component variable mixins are semantically named based on the component being styled, how the style is intended to be used, and the CSS property being targeted
  • Teams must only use component variables when semantically appropriate

# Use When

  • Your project does not use Vue.js, but you want to use Cedar
  • Your component must visually match an existing Cedar component, but not it's functionality. For example, a vue-router link component that looks like a CdrLink component
  • Your project requires the smallest possible bundle size, and your team is willing to take on the additional maintenance cost of using component variables instead of the Vue.js Cedar components

# Don't Use When

  • Do not use the component variables in a non-semantic way. For example, cdr-button-base-mixin should only ever be used to style a button element
  • Do not use component variables to publish clones or forks of existing Cedar components. Instead, work with the Cedar team to find a long term solution to support your use case

# Naming Structure

The naming structure for component variables and mixins is as follows:

  • Namespace: Top level namespace cdr
  • Component: Name of the Cedar component for the exported variable
  • Modifier: Variant of Cedar component for the exported variable
    • Base modifier (base-) indicates variables that apply to all instances of that Cedar component
    • Additional modifiers can be stacked on top of that
    • For example, to make a primary large button you would use the variables that have base, primary, and large modifiers
  • Sub-Element: Indicates a sub-element of a component. For example, cdr-input-base-label-color indicates the color of the label element used inside the input component
  • State: Describes the interactive state that this variable is applied to. These correspond to CSS selectors such as :focus, :active, :hover, :disabled, etc.

# Examples

Namespace Component Modifier Sub-Element State Mixin
cdr- input- base- mixin
cdr- button- secondary- mixin
cdr- breadcrumb- item- linked- mixin
cdr- select- base- label- disabled- mixin

# Resources

For more information on installing and using component variables in your project, view the README.md on GitHub. Additional examples and a list of supported components are located on the cedar-component-variables doc site. There is also a CodeSandbox set up for testing out the component variables.

Questions about when to use component variables? Ask the Cedar team in #cedar-user-support