Skip to content

Latest commit

 

History

History
99 lines (64 loc) · 3.67 KB

CONTRIBUTING.md

File metadata and controls

99 lines (64 loc) · 3.67 KB

Dialtone CSS Coding guidelines

Naming conventions

All Dialtone CSS classes available to users are prefixed with d-.

.d-input {}
.d-stack8 {}

Tokens

Tokens are the values that make up the design system. Colors, sizing, spacing and typography are valid tokens, and are output as variables in the Dialtone CSS. Tokens are defined in the dialtone-tokens package and are always prefixed with dt. Example: var(--dt-color-black-100). See Dialtone Tokens for more information.

Utility classes

Utility classes are named in the following format d-[PROPERTY_ACRONYM]-[VALUE].

.d-ai-center {} // align-items: center
.d-c-pointer {} // cursor: pointer

Component classes

Component class names use the Block Element Modifier (BEM) naming standard.

.d-banner {} // Block
.d-banner__dialog {} // Element
.d-banner--success {} // Modifier

Immutable utility classes

All of our utility classes are set to !important. This is because they are designed to be immutable, and !important is the best way we have of achieving immutability in CSS. Utility classes should only be applied at the application level and not within Dialtone Vue components.

CSS vars

We use CSS vars, also known as CSS Custom Properties in our CSS component classes for better reusability. We should use tokens to apply values to properties within our CSS classes unless a relevant token does not exist. For example, we should use var(--dt-color-black-100) instead of #000000 or var(--dt-space-400) instead of 0.8rem.

Here we set the --avatar--size CSS var to the --dt-size-450 token, and set both the width and the height to reference this variable.

.d-avatar {
    --avatar--size: var(--dt-size-450);
    width: var(--avatar--size);
    height: var(--avatar--size);
}

Now in variation d-avatar--sm, we just set --avatar--size. Width and height will be set for you.

.d-avatar--sm {
  --avatar--size: var(--dt-size-400);
}

Linting

Our code is linted by:

Configuration can be found in:

Your code will be linted automatically on commit.

  • Lint manually: nx run dialtone-css:lint

Folder structure

Here are some important directories to know within the Dialtone repository

  • lib/build: All source code and assets for the Dialtone library.
  • lib/dist: The compiled bundle will be output here upon nx run dialtone-css:build.
  • lib/build/fonts: Fonts we wish to bundle with Dialtone (woff2 format).
  • lib/build/less: LESS files defining our styles. they are processed and transpiled to CSS on build.

Testing

Any changes you make to Dialtone CSS that is used in Dialtone Vue components will be tested in our percy visual tests when you create a pull request. Other than that please manually test your changes on the Dialtone documentation site as well.

Building

Gulp is the task runner we use to build Dialtone CSS. It's configuration can be found in .gulpfile.js. The following tasks are handled within the gulp build:

  • Compilation, minification and output of LESS to CSS.
  • Bundling and output of fonts.
  • Caching for faster local build performance.