@gtomato-web/gtw-sass

GTW Sass

A Sass library.

If you’re new to Sass, checkout 🔗 the official website of Sass

Table of content:

• Installation
  • Yarn
  • NPM
• Usage
  • Without extend/override
    • Example A-1
    • Example A-2
  • Extend/Override global variables
  • Setting up root level styles
    • Root level features
    • Common tags & classes
• Notice
  • About prefix handling
• Contribute

---

Installation

Yarn

$ yarn add @gtomato-web/gtw-sass

NPM

$ npm i --save @gtomato-web/gtw-sass

---

Usage

With Sass modules and 🔗 @use, recommended.

Without extend/override

If you don't need to extend/override any global variable, just put @use '~@gtomato-web/gtw-sass'; on top of every scss file and enjoy!

Example A-1

// *.scss
@use '~@gtomato-web/gtw-sass'; // Place this line at the top of every Scss file

/* Start to write you Scss here if you don't need to override any global variables,
 * otherwise, read the the section below to learn how to extend or override global variables. */

// e.g.
div {
  @include gtw-sass.size-fixed(10px);
}

// Read the online document to know more about other functions, getters, global variables, mixins, and placeholders

Example A-2

▼ If you think gtw-sass is to long and you want to shorthand namespace:

// *.scss
@use '~@gtomato-web/gtw-sass' as gs; // Shorthand gtw-sass to gs

div {
  @include gs.size-fixed(10px);
}

Extend/Override global variables

To extend/override any global variables, create gtw-sass.extend.scss

▼ In gtw-sass.extend.scss:

// gtw-sass.extend.scss
@forward '~@gtomato-web/gtw-sass';
@use '~@gtomato-web/gtw-sass' as gs;

// e.g. Override app-max-width & app-min-width
@include gs.set-setting((
  app-max-width: 5120px,
  app-min-width: 320px
  // etc...
));

// e.g. Added colors to $color-map
@include gs.set-color((
  primary: #273043,
  secondary: #08C986
  // etc...
));

// etc... (breakpoint, font-weight, image, ratio, typography, z-index)

Read document of 🔗 Variables w/ Getter & Setter to learn more about other global variables, getters, and setters.

▼ Once you finished extend/override global variables, in other Scss files:

@use 'gtw-sass.extend' as gs;

// e.g. Get primary color and secondary from $color-map
$primary-color : gs.get-color(primary);

div {
  background-color : $primary-color;
  color            : gs.get-color(secondary);
}

// etc... (Anything else)

Setting up root level styles

GTW Sass also provided some feature for you to easily set up the css environment.

Root level features

▼ Example of using root level features:

// App.scss

//e.g.
@include gs.init();

// etc... (Anything else)

[mixin] init()

This mixin helps to set up normalization and necessary style in html andy body tag (e.g. base font size, font family, body max/min width, etc...)

💡 You may read document of 🔗 [mixin] init() for more information
💡 In case you have not idea about what is normalization. Normalization is some css to make sure all browsers render all elements more consistently and in line with modern standard.

Common tags & classes

▼ Example of using common tag & class bundles:

// App.scss

//e.g.
@include gs.tags-bundle-headings();
@include gs.classes-bundle-typography();

// etc... (Anything else)

[mixin] tags-bundle-headings()

This mixin helps to generate h1-h6 tags styles with the settings of h1-h6 defined in $typography-map

💡 You may read document of 🔗 [mixin] tags-bundle-headings() for more information

[mixin] classes-bundle-typography()

This mixin helps to generate classes styles with the setting defined in $typography-map

💡 You may read document of 🔗 [mixin] classes-bundle-typography() for more information

There are some other tag & class bundles, read document of 🔗 Tag & 🔗 Class to learn more

---

Notice

About prefix handling

GTW Sass prefer to leave the option of adding prefix to CSS properties to our users. Therefore, GTW Sass will only output the Rules without prefix in most of the case. If you need to add any prefix to the compiled CSS, please use PostCSS and Autoprefixer.

▼ For example:

/* GTW Sass output */
div {
  background : linear-gradient(to bottom, white, black);
}

/* GTW Sass WON'T provide the following output */
div {
  background : -webkit-gradient(linear, left top, left bottom, from(white), to(black));
  background : -o-linear-gradient(top, white, black);
  background : linear-gradient(to bottom, white, black);
}

---

Contribute

If you want to contribute, please read CONTRIBUTING for more information

---

^ Back to top