@littlemissrobot/sass-spacing - npm Package Compare versions

Comparing version 0.0.1 to 1.0.0

package.json

 {
   "name": "@littlemissrobot/sass-spacing",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Little Miss Robot spacing setup for defining spacing variables",
   "main": "index.js",
   "scripts": {
-    "start": "NODE_ENV=local ./node_modules/.bin/gulp start --gulpfile .gulp/Gulpfile.js",
-    "build": "NODE_ENV=prod ./node_modules/.bin/gulp build --gulpfile .gulp/Gulpfile.js",
-    "todo": "leasot -x --reporter markdown 'src/**/*.html' 'src/**/*.scss' > TODO.md",
+    "start": "NODE_ENV=DEVELOPMENT ./node_modules/.bin/gulp start --gulpfile .gulpfile.js",
+    "build": "NODE_ENV=PRODUCTION ./node_modules/.bin/gulp build --gulpfile .gulpfile.js",
     "prepublishOnly": "npm run build"
@@ -25,19 +24,27 @@ },
   "files": [
-    "lib"
+    "scss",
+    "_layout.scss",
+    "_typography.scss",
+    "_index.scss"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
-    "@littlemissrobot/stylelint-config": "^1.0.7",
+    "@littlemissrobot/stylelint-config": "^1.0.13",
     "browser-sync": "^2.26.7",
+    "del": "^5.1.0",
     "gulp": "^4.0.2",
     "gulp-postcss": "^8.0.0",
-    "gulp-sass": "^4.0.2",
+    "gulp-sass": "^4.1.0",
+    "gulp-sourcemaps": "^2.6.5",
     "gulp-stylelint": "^13.0.0",
-    "leasot": "^10.0.0",
-    "node-sass": "^4.13.0",
     "postcss-preset-env": "^6.7.0",
-    "stylelint": "^13.3.0"
+    "postcss-scss": "^2.1.1",
+    "stylelint": "^13.5.0"
   },
   "dependencies": {
-    "@littlemissrobot/sass-functions": "^0.1.0"
+    "@littlemissrobot/sass-functions": "^1.0.0",
+    "sass": "^1.26.8"
   }
 }

README.md

@@ -1,164 +0,432 @@
-# Little Miss Robot - Sass Spacing
+# Little Miss Robot - Sass spacing
 
-> This repository contains the logic and functionality to define and insert
-> consistent spacings based on an iteratable amount.
+> This repository contains logic and functionality to define and insert
+> consistent spacing in the form of layout and typography.
 
-## Info
+This package does not contain or generate any CSS. It simply provides a system
+with `@function` and `@mixin` statement to manage spacing. It is part of the
+@littlemissrobot/sass-system package.
 
-This repository does not generate any CSS. It simply makes functions and mixins
-available to be used in combination with a configuration object to manage your
-spacing.
+## IMPORTANT
 
+This library makes use of [Dart Sass](https://sass-lang.com/dart-sass), which is
+the primary implementation of Sass. Make sure that your Sass compiler is making
+use of Dart Sass.
+
+This means that if you are using a task manager (like Gulp) or a module bundler
+(like Webpack), you must indicate which compiler it should use for compiling
+Sass to CSS.
+
+Furthermore, this library makes heavy use of Sass modules:
+[`@use`](https://sass-lang.com/documentation/at-rules/use). Therefore we
+recommend importing and using this library with the `@use` statement.
+
 ## Install
-
 ```sh
+# As a dependency
+$ npm install @littlemissrobot/sass-spacing
+# As a dev-dependency
 $ npm install --save-dev @littlemissrobot/sass-spacing
 ```
 
-## Dependencies
+## Usage
 
-- [@littlemissrobot/sass-functions/lib/main](https://www.npmjs.com/package/@littlemissrobot/sass-functions)
+1. Import the library from the node_modules folder:
 
-## Usage
+```scss
+@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _s;
+```
 
-1. Create a **.scss** file
-2. Import the library from the node_modules folder.
+2. Pass the configuration:
 
 ```scss
-@import
-	// Dependency
-	"@littlemissrobot/sass-functions/lib/main",
-	// Library
-	"@littlemissrobot/sass-spacing/lib/main";
+@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _s with (
+    $baseline: 8px,
+    $baseline-typo: 4px,
+    $system: "linear",
+    $base-font-size: 16px,
+    $base-line-height: 1.5rem,
+    $ratio: "minor-second"
+);
 ```
 
-3. Create a map-variable **$lmr-sass-spacing** and pass it a map with a settings
-and source key. The settings key should have a baseline key which contains
-the base iteratable spacing.
+3. Functionality of the library is now available through the namespace `_s`.
+4. After configuration, the library can be used throughout separate files with
+   partials:
 
 ```scss
-$lmr-sass-spacing: (
-	settings: (
-		baseline: 1rem,
-	),
-	source: (
-		x1: 1,
-		x2: 2,
-		x3: 3,
-		x4: 4,
-		x5: 5,
-		x6: 6,
-		x7: 7,
-		micro: 1rem,
-		tiny: 2rem,
-		small: 3rem,
-		base: 4rem,
-		large: 5rem,
-		huge: 6rem,
-		giant: 7rem
-	)
+@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing/layout" as _sl;
+@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing/typography" as _st;
+```
+
+## Concept
+
+The main focus of this library is to create consistent spacing and visually
+clear [verticaly rythm](https://zellwk.com/blog/why-vertical-rhythms/).
+
+The first part of this library is spacing. This is one of the biggest influences
+in creating a distinguisable brand. Not providing a consistent unit of
+measurement can lead to layout inconsistencies between pages or other projects.
+
+We recommend using multiples of 8, why? Because 8 is divisble by 2 and 4 and
+becomes important when displays multiply pixel sizes due to higher resolutions.
+For example: a resolution of 1.5 would multiply 5px baseline and result in half
+a pixel offset, which might result in an edge that appears blurred. Half pixels
+don't happen on a 8px baseline grid.
+
+The second part of this library is typography. Spacing and typography influence
+each other and should be used together. Mainly the line height place a big part
+in the spacing system. This is due to the fact that line height determines how
+much spacing there is between each line of typography and should be consistent
+with the spacing baseline.
+
+## Configuration
+
+```scss
+@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _s with (
+    $baseline: 8px,
+    $baseline-typo: 4px,
+    $system: "linear",
+    $base-font-size: 16px,
+    $base-line-height: 1.5rem,
+    $ratio: "minor-second"
 );
 ```
 
-## Source
+### $baseline
 
-There are two ways to add keys to the source:
+* **unit**: px
+* **default**: 8px
+* **required**: true
 
-### Pass a number without a unit
+The `$baseline` is the spacing baseline for determining a scale. We recommend
+using 8px, but if you require a smaller value, we suggest using 4px.
 
-Passing a number without a unit will make use of the baseline defined in the
-settings key. The number will be multiplied with the baseline value to define
-a certain spacing. You can give you iterator a name to make it contextual
-or reusable.
+### $baseline-typo
 
-For example:
+* **unit**: px
+* **default**: 4px
+* **required**: false
 
+The `$baseline-typo` is an alternative spacing baseline which should only be
+used for typography. This is done to lessen the gap for line-heights and create
+more variants for typography. This can also be used to create spacing between
+smaller typographic components. But keep in mind, that the `$baseline` should be
+divisble by the `$baseline-typo`.
+
+### $system
+
+* **default**: "linear"
+* **required**: false
+
+The `$system` variable determines how the spacing baseline should be scaled in
+steps. By passing a predefined string, you tell the library how it should scale
+the `$baseline`. The predefined systems are:
+
+* linear
+
+Scales the baseline on a linear scale where each step is a multiple of the
+baseline.
+
 ```scss
-$lmr-sass-spacing: (
-	settings: (
-		baseline: 1rem,
-	),
-	source: (
-		1x: 1, // 1rem
-		2x: 2 // 2rem
-	)
+$baseline: 8px;
+$system: "linear";
+
+// 8, 16, 24, 32, 40, 48
+```
+
+* fibonacci
+
+Scale the baseline where each number is the sum of the two preceding ones.
+
+```scss
+$baseline: 8px;
+$system: "fibonacci";
+
+// 8, 16, 24, 40, 64, 104
+```
+
+* geometric-progression
+
+Scale the baseline where each number is the power and the step its exponent.
+When using this system, we recommend using 2px because it will create more
+possibilities.
+
+```scss
+$baseline: 2px;
+$system: "geometric-progression";
+
+// 2, 4, 8, 16, 32, 64, 128
+```
+
+* custom
+
+Create your own scale by passing a list of numbers to multiply the baseline
+with.
+
+```scss
+$baseline: 16px;
+$system: (0.125, 0.25, 0.5, 0.75, 1, 1.5, 2, 2.5, 3)
+
+// 2, 4, 8, 12, 16, 24, 32, 40, 48
+```
+
+### $base-font-size
+
+* **unit**: px
+* **default**: 16px
+* **required**: true
+
+The `$base-font-size` is the font-size placed on the root element. This is used
+the create different steps based on a ratio and determine the ratio in which the
+line-heights should get automagically calculated.
+
+### $base-line-height
+
+* **unit**: rem
+* **default**: 1.5rem
+* **required**: true
+
+The `$base-line-height` is the line-height placed on the root element or on the
+base typography element: `<p>`. This should be a step from the spacing baseline
+to create a correct vertical rythm.
+
+### $ratio
+
+* **default**: false
+* **required**: false
+
+The `$ratio` is an optional number or a predefined string that can be passed to
+calculate each step for the font-size. To see these in action you can test them
+out in the [modular-scale tool](https://www.modularscale.com/).
+
+The predefined strings and its number are based on the modular scale:
+
+* minor-second: 1.067,
+* major-second: 1.125,
+* minor-third: 1.2,
+* major-third: 1.25,
+* perfect-fourth: 1.333,
+* augmented-fourth: 1.414,
+* perfect-fifth: 1.5,
+* minor-sixth: 1.6,
+* golden: 1.618,
+* major-sixth: 1.667,
+* minor-seventh: 1.778,
+* major-seventh: 1.875,
+* octave: 2,
+* major-tenth: 2.5,
+* major-eleventh: 2.667,
+* major-twelfth: 3,
+* double-octave: 4
+
+## Functions
+
+### rem($value)
+
+Convert a pixel value and to a rem value. This conversion based on the
+$base-font-size determined in the configuration.
+
+Parameters:
+
+* **$value**: The pixel value to convert
+
+```scss
+@use "@littlemissrobot/sass-spacing" as _s with (
+    $base-font-size: 16px
 );
+
+_s.rem(16px); // 1rem
+_s.rem(32px); // 2rem
 ```
 
-### Pass a number with a unit
+## Layout
 
-Passing a number with a unit will simply ignore the baseline and make use of the
-value you have passed to the key.
+These are namespace with **l_**:
 
-For example:
+```scss
+@use "@littlemissrobot/sass-spacing" as _s;
 
+_s.l_step(1);
+```
+
+Or can be included through the partial:
+
 ```scss
-$lmr-sass-spacing: (
-	settings: (
-		baseline: 1rem,
-	),
-	source: (
-		micro: 2.5rem, // 2.5rem
-		giant: 70px // 70px
-	)
+@use "@littlemissrobot/sass-spacing/layout" as _sl;
+
+_sl.step(1);
+```
+
+### Functions
+
+#### step($value, $base, $result-unit)
+
+Calculate a step of the `$baseline`, based on the `$system`. By default this
+will return a number in `rem`.
+
+Parameters:
+
+* **$value**: The step of the baseline
+* **$base** (optional): The baseline to use, this should either be the $baseline
+  or the $baseline-typo.
+* **$result-unit**: The unit in which to return the value in. This can either be
+  px or rem. By default this would be rem and we recommend using rem.
+
+```scss
+@use "@littlemissrobot/sass-spacing" as _s with (
+    $baseline: 8px,
+    $baseline-typo: 4px,
+    $system: "linear",
+    $base-font-size: 16px,
 );
+
+@use "@littlemissrobot/sass-spacing/layout" as _sl;
+
+_sl.step(1); // 0.5rem
+_sl.step(2); // 1rem
+_sl.step(1, _s.$baseline-typo); // 0.25rem
+_sl.step(2, _s.$baseline-typo); // 0.5rem
+_sl.step(1, _s.$baseline, "px"); // 8px
+_sl.step(2, _s.$baseline, "px"); // 16px
 ```
 
-## Functions
+#### snap($value, $base)
 
-### set-spacing($name)
+Calculate the closest step to the passed value, based on the `$baseline` and
+`$system`. Returns a number in the same unit as the passed value.
 
-The set-spacing function accepts a path that it will follow and will look through
-the source defined in the $lmr-sass-spacing map and retrieve the value from the
-passed path.
+Parameters:
 
+* **$value**: The number in pixels or rem used for snapping to the grid.
+* **$base** (optional): The baseline to use, this should either be the $baseline
+  or the $baseline-typo.
+
+```scss
+@use "@littlemissrobot/sass-spacing" as _s with (
+    $baseline: 8px,
+    $baseline-typo: 4px,
+    $system: "linear",
+    $base-font-size: 16px,
+);
+
+@use "@littlemissrobot/sass-spacing/layout" as _sl;
+
+_sl.snap(20px); // 24px
+_sl.step(19px); // 16px
+_sl.step(21px); // 24px
+_sl.step(32px); // 32px
+_sl.step(31px); // 32px
+_sl.step(1rem); // 1rem
+_sl.step(1.2rem); // 1rem
+_sl.step(1.3rem); // 1.5rem
+_sl.step(12px, _s.$baseline-typo); // 12px
+_sl.step(14px, _s.$baseline-typo); // 16px
+_sl.step(13px, _s.$baseline-typo); // 12px
+_sl.step(40px, _s.$baseline-typo); // 40px
+```
+
+## Typography
+
+These are namespace with **t_**:
+
+```scss
+@use "@littlemissrobot/sass-spacing" as _s;
+
+_s.t_ratio(1);
+```
+
+Or can be included through the partial:
+
+```scss
+@use "@littlemissrobot/sass-spacing/typography" as _st;
+
+_st.ratio(1);
+```
+
+### Functions
+
+#### ratio($value, $result-unit)
+
+Used to calculate a step of a font-size based on the `$base-font-size` and
+`$ratio` in the configuration.
+
 Parameters:
 
-* **path**: The path to the spacing value in the `source` key of the map
-$lmr-sass-spacing. It accepts the formats:
+* **$value**: The step of the base-font-size
+* **$result-unit**: The unit in which to return the value in. This can either be
+  px or rem. By default this would be rem and we recommend using rem.
 
-	* A string, like `"section small"` (we like this)
-	* A space-separated list, like `"section" "small"`
-	* A comma-separated list, like `("section", "small")`
+```scss
+@use "@littlemissrobot/sass-spacing" as _s with (
+	$base-font-size: 16px,
+	$ratio: "minor-second",
+);
 
+@use "@littlemissrobot/sass-spacing/typography" as _st;
+
+_st.ratio(1); // 1rem
+_st.ratio(1, "px"); // 16px
+_st.ratio(5); // 1.296rem
+_st.ratio(5, "px"); // 20.739px
+_st.ratio(-5); // 0.723em
+_st.ratio(-5, "px"); // 11.569px
+```
+
+#### line-height($value, $result-unit)
+
+Used to calculate the line-height for a font-size based on the ratio between
+the `$base-font-size` and `$base-line-height` and eventually snap it to the
+closest step of the `$baseline-grid` and its `$system`.
+
+Parameters:
+
+* **$font-size**: The font-size to calculate the line-height for.
+
 ```scss
-// =============================================================================
-// Configuration
-// =============================================================================
-$lmr-sass-colors: (
-	settings: (
-		baseline: 1rem
-	),
-	source: (
-		section: (
-			small: 1rem, // 1rem
-			base: 5, // 5rem
-			large: 9rem // 9rem
-		)
-	)
+@use "@littlemissrobot/sass-spacing" as _s with (
+	$baseline: 8px,
+	$system: "linear",
+	$base-font-size: 16px,
+	$base-line-height: 1.5rem,
+	$ratio: "minor-second",
 );
 
-// =============================================================================
-// Examples
-// =============================================================================
+@use "@littlemissrobot/sass-spacing/typography" as _st;
 
-// As a string
-// -----------------------------------------------------------------------------
-div {
-	margin-top: set-spacing("section small");
-	margin-top: set-spacing("section base");
-}
+_st.line-height(16px); // 1.5rem
+_st.line-height(32px); // 2rem
+_st.line-height(_st.ratio(5)); // 2rem
+```
 
-// As a list of space-separated strings
-// -----------------------------------------------------------------------------
-div {
-	margin-top: set-spacing("section" "small");
-	margin-top: set-spacing("section" "base");
+### Mixins
+
+Calculate the root font-size, based on the base font-size of the system and
+the default browser font-size. Return a font-size in percentage. Should always
+be placed on the root element!
+
+Parameters:
+
+```scss
+@use "@littlemissrobot/sass-spacing" as _s with (
+	$base-font-size: 16px,
+);
+
+@use "@littlemissrobot/sass-spacing/typography" as _st;
+
+:root {
+	@include st.root(); // font-size: 100%;
 }
+```
 
-// As a list of comma-separated strings
-// -----------------------------------------------------------------------------
-div {
-	margin-top: set-spacing(("section", "small"));
-	margin-top: set-spacing(("section", "base"));
+```scss
+@use "@littlemissrobot/sass-spacing" as _s with (
+	$base-font-size: 10px,
+);
+
+@use "@littlemissrobot/sass-spacing/typography" as _st;
+
+:root {
+	@include st.root(); // font-size: 62.5%;
 }
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

57562

increased by365.19%

Number of package files

34

increased by277.78%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

433

increased by162.42%

Worsened metrics

Dependency count

2

increased by100%

Dev dependency count

11

increased by10%

Dependency changes

• + Addedsass@^1.26.8

• + Added@littlemissrobot/sass-functions@1.1.2(transitive)

• + Added@parcel/watcher@2.5.0(transitive)

• + Added@parcel/watcher-android-arm64@2.5.0(transitive)

• + Added@parcel/watcher-darwin-arm64@2.5.0(transitive)

• + Added@parcel/watcher-darwin-x64@2.5.0(transitive)

• + Added@parcel/watcher-freebsd-x64@2.5.0(transitive)

• + Added@parcel/watcher-linux-arm-glibc@2.5.0(transitive)

• + Added@parcel/watcher-linux-arm-musl@2.5.0(transitive)

• + Added@parcel/watcher-linux-arm64-glibc@2.5.0(transitive)

• + Added@parcel/watcher-linux-arm64-musl@2.5.0(transitive)

• + Added@parcel/watcher-linux-x64-glibc@2.5.0(transitive)

• + Added@parcel/watcher-linux-x64-musl@2.5.0(transitive)

• + Added@parcel/watcher-win32-arm64@2.5.0(transitive)

• + Added@parcel/watcher-win32-ia32@2.5.0(transitive)

• + Added@parcel/watcher-win32-x64@2.5.0(transitive)

• + Addedbraces@3.0.3(transitive)

• + Addedchokidar@4.0.1(transitive)

• + Addeddetect-libc@1.0.3(transitive)

• + Addedfill-range@7.1.1(transitive)

• + Addedimmutable@4.3.7(transitive)

• + Addedis-extglob@2.1.1(transitive)

• + Addedis-glob@4.0.3(transitive)

• + Addedis-number@7.0.0(transitive)

• + Addedmicromatch@4.0.8(transitive)

• + Addednode-addon-api@7.1.1(transitive)

• + Addedpicomatch@2.3.1(transitive)

• + Addedreaddirp@4.0.2(transitive)

• + Addedsass@1.80.6(transitive)

• + Addedsource-map-js@1.2.1(transitive)

• + Addedto-regex-range@5.0.1(transitive)

• - Removed@littlemissrobot/sass-functions@0.1.3(transitive)

• Updated@littlemissrobot/sass-functions@^1.0.0