Skip to content

Latest commit

 

History

History
115 lines (84 loc) · 7.11 KB

README.md

File metadata and controls

115 lines (84 loc) · 7.11 KB
Raw

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. See the Cedar docs for more high level information about component variables.

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 @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/rei-dot-com/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;
}

LESS example:

@import '@rei/cdr-tokens/dist/rei-dot-com/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();
}

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

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

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

The example project demonstrates how to use Cedar tokens and component variables to generate a CSS stylesheet that applies Cedar to arbitrary HTML markup.

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.

To add support for a new component, in @rei/cedar update the build/component-variables-transfer.js file to add the name of the vars.scss to the list, add a new JSON file to the /examples directory in this repo, and export that JSON file from /examples/index.js.

Update steps:

  • Ensure that your copy of rei-cedar and rei-cedar-component-variables are in the same directory
  • Run npm run 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.
  • Update the @rei/cdr-tokens and @rei/cedar dependencies in this project's package.json to match the versions used to generate the component variables.
  • Update /examples as needed
  • Run the npm run prepublishOnly script inside this repository to process the imported stylesheets
  • Bump the version of this package

Adding Examples to the Doc-site

The examples generated by this project demonstrate how the component variables can be used to re-create the Vue.js Cedar components. This example code is used on the doc site component variables page.

That data is stored as JSON which uses the following structure:

{
  "name": "cdr-example", // Name used for the doc site section and construction of the example CSS classes
  "notes": [
    "notes/caveats about using these mixins properly"
  ],
  "examples": [
    {
      "name": "default", // Name for this example, used in the construction of the example class name
      "html": "<div class=\"cdr-example-default\"></div>", // HTML demonstrating application of the example class to a plain HTML element
      "scss": ["@include cdr-example-base-mixin;", "@include cdr-example-modifier-mixin;"] // SCSS code used to compile the example class.
      // The classname will be autogenerated using the "name" for this component (cdr-example) combined with the "name" for this example (default)
      // The generated classname should be used in the "HTML" field
      // This SCSS code is also rendered on the doc site in plain text for example purposes
    },
    {
      "name": "nested",
      "html": "<div class=\"cdr-example-nested\"><button class=\"cdr-example-nested-button\"></button></div>",
      "scss": [
        "@include cdr-example-base-mixin;",
        "@include cdr-example-modifier-mixin;",
        ".cdr-example-nested-button { @include cdr-example-button-mixin; }" // Additional nested CSS classes can be defined as needed within the parent example class
      ]
    }
  ]
}

See the examples directory for more instances of how this JSON is constructed, or the Example component to see how this JSON is used in the doc site. The example CSS classes that are generated for the docs can be found in /dist/docs/index.scss and may be useful for debugging updates

Testing Example Code

  1. Pull in updates from Cedar by running the build:variables script in rei-cedar, update example JSON code, or add new example files and export them from examples/index.js as needed.
  2. Run npm run prepublishOnly to build this repo and export the docs data
  3. Run npm link to register your local copy of component variables with these changes
  4. In rei-cedar-docs, stop your dev server and run npm link @rei/cdr-component-variables
  5. Restart the cedar docs dev server and inspect your changes on the components/component-variables page