mobify/stencil — pull request #59 by ry5n (2014-09-03 07:07:25+00:00)
Title: Refine all of Stencil (WIP)

This PR shows what I have in mind for Stencil in the near future and is opened for visibility and feedback. Some of these are breaking changes.

Status: **Opened for visibility**

Reviewers: **@kpeatt @jeffkamo **
Linked tickets: addresses some of #17 and #40; should also address #3 and #25
Linked PRs: includes the changes from #49, #57 and #58

## Changes
- Makes the code style more consistent across the board (doesn’t but should incorporate the linting and combing from #54)
- Right now a component’s configurable variable names typically start with the component name, e.g. `$button-border`. For better clarity esp. when defining these vars in project `_variables.scss`, a more explicit convention of `$button__border` is introduced using `__` as a namespace separator same as in our class names. *This is a breaking change*.
- Config vars now use the following pattern for many variables where it’s sensible to inherit a value from Vellum rather than hard-code a default:

```scss
$component__var: if( variable-exists(var), $var, 10px ) !default;
```

What this does is provide flexible configurability: if Vellum’s variable exists, use it as the default (avoiding unnecessary configuration); otherwise, use a fallback. Of course, if the developer set this variable in their `_variables.scss`, that value will be used.

- Completely re-writes the spacing utils, also a breaking change. These utils now rely on a much more configurable map of named spacings that generates the selector names and style rules. This allows for more flexibility and minimizes file bloat.
- Introduces (as the fallback vars for spacing utils) the notion of a `$v-unit` and `$h-unit`. Instead of declaring the v-space and h-space as the atomic units for spacing, the idea is to declare the *smallest* units of horizontal and vertical measurement – essentially defining a set of core increments for more than just spacing. The values for these should probably be between 4px and 10px (set per-project w/ a default in Vellum), ensuring a granular base and a relatively common concept of what values they hold across projects. `$v-space` and `$h-space` could be derived from these basic units.

## How to test-drive this PR
- mostly code review