Gravy is a SCSS foundation library
Q: What is a foundation library?
A: Is a library that provides basic essential functions and mixins to solve some basic requirements for any project.
Q: Why Gravy?
A: Because it gives flavour to what you have on your plate without much effort...
Q: What does Gravy provide?
A: For now, typographical enhancements (suggestions and feature requests are always welcome).
This library depends on the following libraries:
- Typi for responsive typography and vertical rhythm.
The dependencies are meant to aleviate the amount of effort to achieve a particular solution. If you feel like there's a reason to ditch a particular dependency in favour of a localised solution, please open a bug request.
Additional dependencies needs to be handled by your own project, you most likely want to have the following installed and configured before Gravy:
- Normalize-scss as a SCSS module for Normalize.css .
- Modularscale-sass for typography following Modular Scale principles.
Install the library via npm, the usual way:
$ npm install @buildit/gravy
Otherwise, if you don't want to customise anything, just include the whole path:
You can then configure it by creating the Gravy configuration map.
Once that's done, you need to call the initialisation mixin that will generate the necessary configuration maps and base CSS output:
The configuration comes simply by setting the required sub-maps in the main
$gravy map, you can set one or more of the following keys in you project,
gravy-init will fill in the rest with the following default values.
$gravy: ( base-font-size: 16px, base-line-height: 1.4, breakpoints: ( small: 600px, large: 1200px ), typefaces: ( primary: ( stack: ('Arial', sans-serif), weights: ( regular: 'regular', bold: 'bold' ) ) ), typi: ( base: ( null: (16px, 1.4), small: (16px), large: (19px) ) ) );
More technical documentation in HTML format can be found in the
Generated and reserved variables
gravy-init will parse the
$gravy config map, and generate some additional non-scoped variables that are going to be used by either the dependencies or some of the mixins available by the tool.
$base-font-size: handy variable for the size in pixels of the base font size.
$base-line-height: unitless variable for the size of the line height.
$breakpoints: will contain a list of named breakpoints. These will have to be used in the configuration map of
typithat can be retrieved using the mixin
$typefaces: will contain a list of named font faces, e.g. 'primary', 'headings', ...; you can later output the correct
font-weightusing the mixin
gravy-font($name, $weight: 'regular')each font face contains the following keys:
stack: a map containing the list of font families to use.
weights: a list of weights for the selected font, like 'regular', 'bold', ... .
$typi: the typi configuration map. Refer to typi documentation for information on how this works. You'll be then able to use the mixin
typi($name)to generate the needed
line-heightat different breakpoints.
gravy-breakpoint($name): outputs the actual size given the name set in the
breakpointmap (see Generated and reserved variables section).
gravy-init: does the initialisation of all the needed functions, needs to be called after all the needed maps have been configured and before calling any other function or mixin.
gravy-font($name): generates the
font-weightbased on the
typefacesmap (see Generated and reserved variables section).
Modularscale and typi font sizes
If you want to use to use Modularscale, you can do so by installing
modularscale-sass via npm, and configure it before calling
Contribute & support
You can contribute to the development of this library in many ways:
- submitting bug reports,
- opening PRs,
- getting in touch with our core developers if none the above works (we'll try to answer all of your love letters!).
NOTE Be sure to enable stylelint in your preferred IDE/Editor, or run
npm test before pushing and opening a PR: any PR submitted that doesn't lint correctly will be rejected.