Skip to content
Variables and mixins exported from Cedar design system components
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
examples
public
src
.gitignore
README.md
babel.config.js merge docs into main project Apr 30, 2019
build-stylesheet.js
deploy.js
package-lock.json
package.json
sass2less.js
vue.config.js

README.md

cdr-component-variables

Component variables provide a versioned method for teams to import the exact CSS styles being used in the Cedar vue components and apply them to elements in their project. For example, this package makes available variables like $cdr-button-base-border-radius which is the border-radius value for all Cedar button components, as well as mixins like @include cdr-button-base-mixin which sets many properties on an element including the border-radius. Most developers will want to use the mixins as they will be easier to maintain in the long term, however the variables are available if you require more control over styling.

These variables and mixins are intended to be used to match the styling of the component/element that they correspond to. For example, $cdr-button-base-border-radius should only be used to style the border-radius of a "button-like" element. If you use that variable to set the border-radius on something that is not a button, then that element would be affected any time the Cedar button border radius is changed.

Each component has a set of base mixins which apply to all Cedar components of that type, as well as modifier mixins which control the size and appearance of that component. For example, to create a Cedar primary button you would create a class that includes @include cdr-button-base-mixin; @include cdr-button-primary-mixin;, whereas if you need a Cedar secondary small button you would create a class that includes @include cdr-button-base-mixin; @include cdr-button-secondary-mixin; @include cdr-button-small-mixin;. See the docs page for more examples.

supported components

See the docs page for a list of supported components and examples of how they can be used. If there is a component that you would like to see supported, please open an issue here. If you are trying to build a component that is not in Cedar, you should instead use the design tokens.

install

The component variables inherit values from the design tokens, so you will need to install both packages:

npm install --save-dev @rei/cdr-tokens@1.0.0 @rei/cdr-component-variables

Your project must be able to compile SCSS or LESS in order to make use of this package.

This package contains /dist/less and /dist/scss folders, each of which contains *.vars.{less|scss} for each component, as well as an index.{scss|less} that imports all of those files. It is recommended that you use the index file to ensure that all variables are loaded in the correct order. A dist/{scss|less}/cedar-component-variables.{scss|less} file is also available which concatenates all of the variable files together.

usage

SCSS example:

@import '@rei/cdr-tokens/dist/scss/cdr-tokens.scss'; /* import the tokens file */
@import '@rei/cdr-component-variables/dist/scss/index.scss'; /* import the component variables */

.your-button-class {
  /* use mixins to apply many properties at once */
  @include cdr-button-base-mixin;
  @include cdr-button-primary-mixin;
}

.your-other-button-class {
  /* use variables if you need to apply specific properties */
  border-radius: $cdr-button-border-radius;
}

LESS example:

@import '@rei/cdr-tokens/dist/less/cdr-tokens.less'; /* import the tokens file */
@import '@rei/cdr-component-variables/dist/less/index.less'; /* import the component variables */

.your-button-class {
  /* use mixins to apply many properties at once */
  .cdr-button-base-mixin();
  .cdr-button-primary-mixin();
}

.your-other-button-class {
  /* use variables if you need to apply specific properties */
  border-radius: @cdr-button-border-radius;
}

The docs page demonstrates which mixins to use to achieve various styles for each supported component.

You can find all of the exported variables and mixins in the /dist directory.

If you are unsure of how a variable or mixin is intended to be used, you can search for the variable name in the Cedar component source.

development

The /dist folder in this project should never be edited directly as it is meant to stay in sync with Cedar. This package should be updated whenever component variable support is added to a new component, or whenever the markup/styling for a supported component changes.

Update steps:

  • Ensure that your copy of rei-cedar and rei-cedar-component-variables are in the same directory
  • Run the build:variables script in rei-cedar to copy the variable files for all supported components into this repository. If you are adding support for a component, you will need to update that build script. If there are no changes to the /dist directory, then there is no need to do anything else.
  • Run the build:less script inside this repository to create a LESS copy of the previous SASS export
  • Update the cdr-tokens dependencies in this project's package.json so that the version exactly matches the version currently being used in rei-cedar
  • Update /examples as needed. Note that you will need to re-start the serve script any time the example SCSS code changes.
  • Bump the version of this package
  • Run the build:docs script in this project
You can’t perform that action at this time.