@sagent/brand v0.0.37

Sagent Brand

USAGE

1. Example ( @use keyword is a recommended way to import sass, it replaces @import, which will be depricated eventually):

// Externally
@use "variables" as vars;

h3 {
  color: vars.$c-accent;
}

// Internally in the lib (relative path)
@use "../variables" as vars;

h3 {
  color: vars.$c-primary;
}

2. Library also contains 2 stylesheet files (part of build.options in angular.json):

    ...
    "styles": [
        "node_modules/@sagent/brand/src/lib/scss/styles/_styles.scss",
        "node_modules/@sagent/brand/src/lib/css/_styles.css",
        ...
    ],
    ...

HOW TO ADD ADDITIONAL FILE TO EXPORTS

1. Add file to ng-package.json "assets".
2. Add file to the package.json "exports".

CREATE NEW LIB

1. Generate a new lib using nx generate with options (based on the needs)

    --style=scss
    --change-detection=OnPush
    --import-path=@sagent/example
    --publishable
    --tags=utils

2. Change path (for all environments) for tsconfig in "targets": "build": "configurations": "production": "tsConfig" to "tsconfig.lib.prod.json" (folder path needs to be removed)

3. Add scripts to package.json of the lib (replace lib name placeholder):

    "scripts": {
        "patch": "npm version patch",
        "pack": "cd ../../dist/libs/[LIBRARY NAME] && npm pack && npm publish --access public",
        "publish": "npm run patch && nx build && npm run pack"
    }

4. Add tags to the lib for proper boundaries maintenance in project.json

    "tags": ["scope:some-scope", "type:[app or feature or utils]"]

5. To publish the lib you will need to login into npm first:

    npm adduser

6. Now you can build and publish with one script from the monorepo root folder

    npx nx publish [lib_name]

HOW TO LINT SCSS IN AN APP/PROJECT

0. Install npm package

    npm i --save-dev @sagent/brand

1. Install stylelint

    npm install --save-dev stylelint stylelint-config-standard-scss

2. Add script (optional) to package.json of the app

    {
        "scripts": [
            "style-lint": "npx stylelint \"**/*.scss\"",
        ]
    }

3. Add config file to the root of the app/lib .stylelintrc or .stylelintrc.json

{
  "extends": ["stylelint-config-standard-scss", "./src/lib/stylelint/sagent-stylelint-rules"]
}

4. Run script

    npm run style-lint

NESTING

Ideally there should not be more than 2-3 levels of nesting. If selectors are named properly, thre is no need for deep nesting.

NAMING CONVENTION

1. The project is utilizing mixed approach in naming css selectors.
2. If css selector is used in any DOM query (ex: document.querySelector('.some-class')) use ts- prefix, so that other developers will be aware.
3. Use top level wrapper/container for every component (there should almost no exceptions). Lets say you have a component a tag <prefix-some-tag></prefix-some-tag>. Then inside its template should look like this (prefix should be omitted):

<div class="some-tag">...</div>

4. Use hyphen to separate words in the selector:

    .some-smart-component {
        ...
    }

5. For inner selectors, when they are part of component or always supposed to be used together, use low dash "_" to separate parent name, item itself and modifier:

    // NAME STRUCTURE
    .[component/feature-name]_[item-name]_[modifier] {

    }

    //
    .some-smart-component_title {
        ...
    }

    // MODIFIER IS OPTIONAL
    .some-smart-component_title_large {
        ...
    }

    .some-smart-component_image {
        ...
    }
    .some-smart-component_content {
        ...
    }

No mater how deep your element sits inside component, as long as it is part of it, the selector should use the same naming convention. In the example in #6 the image tag (grandchild of the component) has a class some-smart-component_image and not some-smart-component_content_image.

6. So the html will look like this:

<div class="some-smart-component">
  <div class="some-smart-component_title">...</div>

  <div class="some-smart-component_content">
    ...
    <img class="some-smart-component_image" />
  </div>
</div>

7. Well-structured comments can save time when you’re trying to understand your code. You do not need to write comments to say color: red will give a red color. But, if you’re using a CSS trick that is less obvious, feel free to write a comment.

   Take a look at how well commented the Bootstrap source code is.

WHERE SHOULD I PUT MY STYLES?

If you are working on any design/style changes please follow the following guide:

1. Rule will be (or may be, or should be) used by more than 1 project: @sagent/brand.
2. Rule will be used AND shared between components only inside a single project: styles.scss in the project root or in any corresponding file name inside project /styles folder.

    // src/styles.scss

    // OPTION 1 - Reference another shared/global scss file
    @use './styles/feature_name.scss';

    // OPTION 2 - Directly in styles file
    .some-class {
        ...
    }

3. Rule will be used only by a single component: .scss in the component folder.

DO and DON'T

To maintain the syntax for multi theme support every developer should be aware of DOs and DON'Ts. This will also make the app design more consistent and will provide a better UI.

DON'T USE:

• color literal, only use color variables or mixins.

// WRONG
.foo {
  color: #ffffff;
}

// CORRECT
.moo {
  color: vars.$c-primary;
}

• background color literal, only use mixins. In this case color will be determined by a mixin, do not specify a font color as well:

// WRONG
.foo {
  background-color: #0000ff;
  color: grey;
}

// CORRECT, notice there is no color property.
.moo {
  @include mixins.color-bg("primary-dark");
}

• font/font-family/font-size/font-weight/letter-spacing properties directly, only use font mixins. A need for a new font has to be addressed by a designer and (if it is needed) it should be added to the @sagent/brand font mixin:

// WRONG
.foo-title {
  font-family: Arial;
  font-size: 54px;
  font-weight: 600;
}

// CORRECT
.moo {
  @include mixins.font("title-medium");
}

• margin/padding literals, only use variables (recommended) or rem units. There can be some exceptions, but they should not become normal:

// WRONG
.foo-title {
  margin: 6px 10px;
  padding: 7px;
}

// CORRECT
.moo {
  margin: vars.$space1x vars.$space2x;
  padding: vars.$space1x;

  // same as
  margin: 0.5rem 1rem;
  padding: 0.5rem;
}

// SOMETIMES, BUT RARE. Usually when margin/padding is too small (tooltips, badges, some icons, etc):
.too {
  padding: 1px 2px;
}