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
If you have Eyeglass or sass-module-importer
installed, you can simply include the symbol Gravy exports to your main scss file:
@include "gravy";
Otherwise, if you don't want to customise anything, just include the whole path:
@include "node_modules/gravy/sass/gravy";
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:
@include gravy-init;
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 docs/
folder.
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 oftypi
that can be retrieved using the mixingravy-breakpoint($name)
.$typefaces
: will contain a list of named font faces, e.g. 'primary', 'headings', ...; you can later output the correctfont-family
andfont-weight
using the mixingravy-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 mixintypi($name)
to generate the neededfont-size
andline-height
at different breakpoints.
gravy-breakpoint($name)
: outputs the actual size given the name set in thebreakpoint
map (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 thefont-family
andfont-weight
based on thetypefaces
map (see Generated and reserved variables section).
If you want to use to use Modularscale, you can do so by installing modularscale-sass
via npm, and configure it before calling typi-init
.
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.