Sagent Brand
USAGE
- 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;
}
- Library also contains 2 stylesheet files (part of
build.options
inangular.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
- Add file to ng-package.json "assets".
- Add file to the package.json "exports".
CREATE NEW LIB
- 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
-
Change path (for all environments) for tsconfig in "targets": "build": "configurations": "production": "tsConfig" to "tsconfig.lib.prod.json" (folder path needs to be removed)
-
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"
}
- Add tags to the lib for proper boundaries maintenance in
project.json
"tags": ["scope:some-scope", "type:[app or feature or utils]"]
- To publish the lib you will need to login into npm first:
npm adduser
- 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
- Install npm package
npm i --save-dev @sagent/brand
- Install stylelint
npm install --save-dev stylelint stylelint-config-standard-scss
- Add script (optional) to package.json of the app
{
"scripts": [
"style-lint": "npx stylelint \"**/*.scss\"",
]
}
- 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"]
}
- 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
- The project is utilizing mixed approach in naming css selectors.
- If css selector is used in any DOM query (ex:
document.querySelector('.some-class')
) usets-
prefix, so that other developers will be aware. - 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>
- Use hyphen to separate words in the selector:
.some-smart-component {
...
}
- For inner selectors, when they are part of component or always supposed to be used together, use low dash "
_
" to separateparent name
,item itself
andmodifier
:
// 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 notsome-smart-component_content_image
.
- 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>
-
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:
- Rule will be (or may be, or should be) used by more than 1 project:
@sagent/brand
. - 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 {
...
}
- 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;
}