mobify/vellum

Default project styles for a mobile-first AdaptiveJS build.

Vellum

Default Sass styles and variables for a mobile-first site build using Spline.

Efficient

Vellum is written to help designers and developers of mobile-first projects get started quickly by defining a set of variables, typographic hierarchy, and default styles.

Customizable

This is just the beginning. Vellum is made to be customized for your project. Think of Vellum like tracing paper: it gets you started but the lines are all your own.

Extensible

Vellum comes with an easy to comprehend variable naming system so you can easily extend it with new elements and new styles. Think you’ve added something every project needs? Commit it back into the project.

The Idea

Vellum is built to get Mobify Adaptive.js projects off the ground quickly. It provides variable definitions, base typographic and form styles, and mobile-first defaults. It’s based on our mixin library, Spline and relies on Autoprefixer for prefixing.

Vellum is made to be as unopinionated as possible while still providing a bunch of sane defaults you can use for your projects. Install it in your Sass directory and bend it to your whim. Feel free to change anything and everything to match your project’s needs.

Requirements

• Sass
• Spline
• Autoprefixer

Installation

We don’t provide Vellum through a package manager because it’s made to be edited.

1. Install Spline.

   bower install spline

2. Clone this repository and copy everything in the dist folder into your Sass folder.

3. Install some form of Autoprefixer. We use Grunt so we recommend grunt-autoprefixer.

4. As the first thing in your main scss file, import Vellum’s variables. Then, after Spline and Normalize, import Vellum’s base styles. Any additional stylesheets should be included after base styles.

   @import "variables"; // Import variables first
   @import "bower_components/spline/dist/spline";
   @import "bower_components/modularized-normalize-scss/normalize";
   @import "base"; // Import base styles after Sass libraries and normalize
   

Using Vellum

Folder

/base/

You should treat Vellum’s base folder as your project base styles – that is, global styles for built-in HTML elements. Edit, update, add, or remove code from the existing files and/or add new ones to the directory.

Main File

_base.scss

This is the main import file. It explains each of the different files being imported as well as gives you a place to add more files.

Variables

_variables.scss

The variables file is where we set the majority of default values used throughout Vellum and your project. Follow these rules to get a better understanding of how the variable section is structured.

Variables are formatted using the following rules:

• Names should be lowercase and dash-separated;
• Qualifiers should be added to the beginning of related variables: use $small-font-size, not $font-size-small;
• Numeric scales should use increments of 10; these numbers are arbitrary and should not map to actual values. If really necessary, additional values can be added in between, e.g. $neutral-15 between 10 and 20.

Layout

Core values for maintaining consistent sizing, spacing and layout throughout a project. We define $unit as the basic unit for sizing and alignment, and $tap-size as the minimum tap-target size, useful for sizing actionable elements.

If you prefer several distinct variables for spacing, such as $v-space or $h-space, add these here. In general these should be derived from $unit.

Typography

Standard font families and typographic settings are set in this section.

Colour Palette

Set up the set of core colours for your project here.

Gradients

Variables containing frequently-used gradients. e.g. background-image: $light-grey-gradient;

To reverse a gradient, you can use the Spline function reverse-gradient() e.g. background-image: reverse-gradient($grey-gradient);

Appearance

Any variable pertaining to default appearance should be declared here, including default colors for text, border styles and input/form styles.

Z-Index

Organizes z-index usage by providing a set of named layers. Values can be incremented/decremented slightly as necessary. eg. $stage-layer + 1;

1. $backdrop-layer should be used for purposefully placing an item behind a staged item. Likely an element that is used as a background.
2. $stage-layer should be your first choice for moving an item in front of others. Likely an icon or an interface element.
3. $orchestra-layer should be used to explicitly place content in front of the stage. Likely a modal shield.
4. $frontrow-layer is your last resort for moving content forward. Likely a modal dialog.

Shorthand Variables

This is a place to collect quick ways to write certain properties that you re-use often.

The Mobify CSS Triforce

Vellum is part of the Mobify CSS Triforce: a collection of three UI Development projects built for making mobile e-commerce builds easier.

• Spline: A mobile-first mixin and function library for Sass.
• Vellum: A set of default styles for mobile-first builds.
• Stencil: A library of common UI patterns for mobile e-commerce builds.

Special Thanks

Vellum was built with a whole lot of care by Mobify. If you’ve got things you’d like to see added or removed, please submit an issue or PR on GitHub.

We also owe a lot of thanks to Thoughtbot’s bitters which Vellum was inspired by and draws a lot of its work from.

License

MIT License. Vellum is Copyright © 2014 Mobify. It is free software and may be redistributed under the terms specified in the LICENSE file.

vellum's Issues

Rewrite contentinfo boilerplate at bottom of test/index.html

We’ve got some boilerplate contentinfo at the bottom of the test html file that has wrong copyright and attribution.

Write readme

Need to write a readme with the hows but also the whys of the project.

Figure out how this integrates with generator-adaptivejs

I think Ted’s got this one, but I guess we should discuss, and document.

Some variable names are misleading

In _forms.scss for example, we use variables like $forms__border-color. Since all Sass vars are global, to me this implies a configurable variable for the Forms component, which it isn’t. The goal of using the __ convention for variables is the same as with our BEM convention: stuff specific to a component. Since Vellum is our global defaults, I don’t think Vellum should use the double-underscore at all: these are vars intended for use by any stylesheet. So in the example, I believe this should be forms-border-color and likewise throughout Vellum.

Stop using rems by default

Switching to rems is probably overkill for now. We may want to explore this again later with mobile/tablet builds but it doesn't give us the benefit we need at this moment. Adds too much mental overhead along with learning all the other new systems.

Should there be a default-ol/ul class, in addition to the placeholder class?

Ala...

%default-ul,
.x-default-ul {
}

%default-ol,
.x-default-ol {
}

The reasoning being to avoid the potential for large numbers of @extends and the CSS bloat that comes along with that.

Of course, the flip side would mean we'd have to add classes to all ul or ol which is also not terribly ideal.

Not sure which is better, so... thoughts?

Rename vellum/_general.scss to vellum/_document.scss

General is a vague term; “document” better captures that this is the defaults for top-level document elements, like html and body, and stuff like *. “Document” is also probably better than “global”, since in CSS, everything is global.

People referencing old variable names should get a warning in their compiled output

Instead of just dropping support for our old variable naming syntax, we should lead people in the right direction through the use of a _deprecated.scss file with a list of old variable names. These variables would point at their new counterparts but would warn users that these variables will no longer be supported in the future. This should make moving over to the new system a little less painful.

Reduce number of gradients

The gradient section is a little overwhelming – most of these will have to be edited per-project. We should reduce these to greyscale gradients (main, light, dark) and perhaps one for brand-color if we keep that variable. We can still include suggestions of other common gradients as a comment.

Remove $base- prefix from variables to make them more concise

Clean up bower stuff

bower.json is the package manifest, why is it in /tests? It should be in / where it belongs.

Also, we shouldn’t be committing our dependencies since this is not intended for standalone consumption. Bower’s own advice is If you aren’t authoring a package that is intended to be consumed by others (e.g., you’re building a web app), you should always check installed packages into source control.. The implication is that if you’re building a reusable component or package, there’s no need to commit dependencies.

Applying box-sizing to :before/:after globally causes paint issues on Android

Remove extraneous color variables

In general, Vellum should be as simple as possible, allowing us to add complexity where necessary per-project. We’ve made variable naming more consistent in #29, are removing some gradient variables in #34. We can simplify colour variables too by removing redundant declarations.

For example, we don’t gain anything by having $xdark-grey and $grey-50 refer to the same value, because they have the same meaning/purpose. However, $grey-50 and $font-color may reasonably assigned the same value, because these two are not intrinsically related.

As it stands, this means we can remove the entire Definitions section.

Select default styles miss padding and down caret on Android 4.3 Galaxy S3

See image bellow - padding and down caret are missing in <select> element

Consider comment examples as alternative to defaults

For variables especially, sometimes we want to provide a helping hand, but we’re dealing with a 20% use case. To keep things simple and encourage folks to add/remove what they need, consider a standard format for “extra suggestions” in the defaults.

For example, where before we might have included a set of colours like so:

$foo-color: #f00;
$foo-light: lighten($foo, 10%);
$foo-dark: darken($foo, 10%);

We can just do this:

// Consider: $foo-color, $foo-light, $foo-dark

Concise, still provides some help, but stays out of your way (easier to delete if not needed).

Consider breaking variables into own repo

Right now Vellum provides both variables and base styles. If we import the vellum library as a whole (which should be encouraged), then we have to import Spline before it if we want access to its mixins and functions in Vellum. But that means that Vellum can’t set any configurable variables in Spline until after Spline is imported. Normally this isn’t an issue, but it’s generally good practice to import variables as the very first thing, in case a library computes anything internally that wouldn’t get set by a late variable import.

Breaking variables into a separate repo that Vellum depends on would make this a non-issue: we import variables, libraries, then Vellum.

This also would allow us to more easily depend on just variables in Stencil components if we decide that we shouldn’t depend on Vellum in components. After all, Vellum can be edited on projects to any state, so it should hardly be considered a reliable dependency for components. However, we still want to be able to depend on some shared variables in our components.

What should $v-space value be by default?

Right now we have to do a rounding calculation on $v-space by default because we're saying it's half of $line-height. I'm wondering how people even end up using this property. Is it usually half of line height like we're saying or do people usually change it?

I know I personally tend to set these as actual values — ie. 10px / 20px or something like that. Thoughts?

---

Change to 10px?

• designer/ui dev + 1
• designer/ui dev + 1

Choose better names for "Sizes" and "Sizing" in Variables

These two words are far too close together.

I assume the roles of these variables are differentiated by: one being for typography, the other is sizes unrelated to typography (i.e. border radius).

Consider adding a pre-release “master” branch

Vellum is different than most projects: it’s not installed as a package, but instead downloaded from the master branch each time an adaptivejs project is generated. For more control over what code is “released” while still being able to freely merge PRs, I propose we create a new branch, pre-release, pre, edge or similar that we use as the target for all new PRs. We should track features with GitHub milestones and merge pre-release into master based on those milestones.

Resolve default line-heights

Now that we have the $v-space variable, line-height should not be of pixel values.

Additionally, this value should probably be replaced with the $line-height variable.

Establish a consistent, flexible, sensible naming convention

Our existing variable naming is pretty good, but it could use some polish. Here are some issues:

• Sometimes we prefix with base, sometimes not: $base-font-size vs $margin;

• Sometimes we use dashes, sometimes not: $light-brand vs $grey10;

• Sometimes we place a qualifier word before, sometimes after: $light-gradient vs. $layer-overlay;

• Adding $base in front of “default” variables gets verbose, since most of our variables fall into this category;

• Placing secondary or modifier parts of the variable name at the end sometimes results in awkward or downright ugly/hard-to-understand variable names, e.g.

  $accent-color-light; // This is fine.
  $font-family-form; // But this is terrible. `$form-font-family` is much clearer.

• Placing the main part of the variable name at the end of the variable makes names in a list harder to scan, e.g.

  $brand: $blue;
  $light-brand: lighten($brand, 60%);
  $dark-brand: darken($brand, 60%);

In #26, I proposed a solution that I’m pretty sure none of us likes. Let’s come up with a better one.

Reduce complexity of vellum/_variables.scss

I think there’s just too much in the variables file. Defaults like Vellum need to err on the side of usefulness for 80% of cases, and should be as quick to understand for newcomers as possible. In particular:

• $sans-serif and $serif aren’t very useful. $text-face, $heading-face, $display-face, $caption-face would be more appropriate for a wider range of projects, although we can/should provide a single $text-face variable and simply suggest additions in a comment.
• All default vars should be intended for use in-project. Avoid variables with the same value and the same use case. In particular, we should avoid things like: $grey10: $xlight-grey. N.B. assignment of variable to variable is not the problem. $text-color: $grey-10 is useful in moderation.
• Simplify colours:
  • Remove default named colours, e.g. $blue, $green, $red. We should either remove them completely, or use CSS keywords red, green, blue as these will need to be set per-project anyway.
  • Ambiguous colour variables, such as $success, should have a -color qualifier, so $success-color;
  • $base- prefix is often redundant: in terms of defaults, we’ll never need a border-radius variable that isn’t base. In particular projects, more specific values can use the form $another-border-radius or $border-radius-foo.
• Simplify the rest:
  • reduce the number of gradients provided by default.
  • remove Shorthand Values section.
  • For things that aren’t 80% use cases, replace boilerplate with concise suggestions as comments.

Vellum has several lines that break our CSS style guidelines

Running Vellum through SCSS Lint shows several warnings that need to be fixed:

dist/vellum/_document.scss:14 [W] Files should end with a trailing newline
dist/vellum/_forms.scss:23 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_forms.scss:24 [W] Shorthand form for property `margin` should be written more concisely as `0 0 $v-space` instead of `0 0 $v-space 0`
dist/vellum/_forms.scss:38 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_forms.scss:75 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_forms.scss:110 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_forms.scss:145 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_forms.scss:161 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_forms.scss:177 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_lists.scss:16 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_lists.scss:23 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_lists.scss:29 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_lists.scss:34 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_tables.scss:5 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_tables.scss:11 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_tables.scss:18 [W] Line should be indented 4 spaces, but was indented 2 spaces
dist/vellum/_tables.scss:18 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property
dist/vellum/_tables.scss:19 [W] Line should be indented 4 spaces, but was indented 2 spaces
dist/vellum/_tables.scss:25 [W] Line should be indented 4 spaces, but was indented 2 spaces
dist/vellum/_typography.scss:87 [W] Properties should be sorted in order, with vendor-prefixed extensions before the standardized CSS property

Should Vellum `@extend` components or vice versa?

This is a continuation of the discussion started in #54.

Variables: use `-gradient` the same way as the `-color` suffix.

In PR 15 we’re firming up naming conventions for colour variables. The gist is that colours always get a -color suffix, e.g. $brand-color and additional suffixes go on the end, e.g. $brand-color-light. We should use the same convention for gradients, using a -gradient suffix. So:

// Neutrals
$grey-gradient: linear-gradient($grey-10, $grey-20);
$grey-gradient-light: linear-gradient(white, $grey-10);
$grey-gradient-dark: linear-gradient($grey-30, $grey-40);

Input placeholders are vertically misaligned on Android 4.3 Galaxy S3

Found out that on Android 4.3 Galaxy S3 input placeholders are vertically misaligned. This can be device specific issue, I saw it on Schrodinger

Determine a consistent neutral color scale

In #69 @cole raised an issue with our greyscale variables not matching the HSL lightness scale. In the ensuing discussion, we discovered that we were not all on the same page on how to use our greyscale color variables. We agreed that having a change-able scale (with different values across projects) created extra friction with inconsistent variable names across projects. We agreed that a resemblance of the variable name to an actual color value wasn’t desirable.

Action items:

• Designers to discuss what they need in terms of a neutral color scale
• Need to gather data on the number of neutral variables used on recent projects (this should help determine the default number of steps and look for other patterns)
• Designers and should then agree to conform to a basic scale where colors can be added to the scale on specific projects.
• Allow $neutral- variables in project stylesheets? (Y/N) → answer: Y, but prefer an application-specific variable such as $border-color wherever possible

Dust templates in Vellum are misleading

I had forgotten that we’d added dust templates to Vellum. This seems strange to me. Yes we want example markup, but putting it in dust files is misleading. When I see a dust file, I expect that I’m supposed to use it as dust rather than writing out the markup by hand.

I would suggest:

• At least, change the extension to .html (they contain no actual dust syntax).
• If these are documentation, they should live in the readme
• If these are for testing or demo purposes, they should live in tests/visual (debatable, but matches Stencil)

Add a function to reverse a linear gradient

It’s useful to be able to do reverse($gradient-light) if $gradient-light contains a standard gradient string. Not sure if this is possible without specifying the gradient in a different format (Sass list)?

Table styles may be too prescriptive

@jeffkamo @ry5n: We built the table styles thinking that we'd be working with good markup; however, these styles do not take into account the fact that we may be dealing with structural tables instead of data tables. Do you think we should pull back on the styling on these guys or are we okay to leave what we have in?

This was a concern @avelinet raised with Orchard Brands so if you have any thoughts, feel free to add them.

Create swatches template

We should have a template for color swatches that we can use to build out a complete list of all available colors for our projects. This would likely only be used in our living style guide, Almanac.

width: 100% to button and [type="submit"]

Do we need to set button and [type="submit"]width to 100%? There is width issue with button component from Vellum elements. I had to add width: auto to button component to override 100% width from Vellum.

https://github.com/mobify/stencil/edit/add-vellum/dist/components/button/_button.scss?pr=/mobify/stencil/pull/106

Test page markup is (still a little) weird/busted

Multiple h1 tags without sectioning wrappers:

<h1 id="main">Vellum example page</h1>
…
<h1 id="swatches">Colors</h1>
…
<h1 id="headings">Headings</h1>

Ids are snake_case; normally we write kebab-case in HTML:

<label for="text_area">Text Area:</label>
<textarea id="text_area"></textarea>

Fieldset wrapping a form is weird, in this case not really correct (a fieldset should wrap a set of related fields):

<fieldset>
    <p>…</p>
    <form>…</form>
</fieldset>

Labels uses where a fieldset + legend would be appropriate: this is what a fieldset is actually for. (FYI the label wrapping input is also weird but is being fixed in #74.)

<p>
<label for="radio_buttons">Radio Buttons:</label>
<label><input type="radio" class="radio" name="radio_button" value="radio_1" /> Radio 1</label>
…
</p>

I’d give the table markup a C- grade: cellspacing and cellpadding aren’t needed anymore; the first <tr> should be a thead with a tbody after containing the other rows. The even class is also no longer needed. “Division” is not what <td> stands for: it’s “table data”, but this should just say “Cell 1” etc.

<table cellspacing="0" cellpadding="0">
    <tr>
      <th>Header 1</th><th>Header 2</th><th>Header 3</th>
    </tr>
    <tr>
      <td>Division 1</td><td>Division 2</td><td>Division 3</td>
    </tr>
    <tr class="even">
      <td>Division 1</td><td>Division 2</td><td>Division 3</td>
    </tr>
    <tr>
      <td>Division 1</td><td>Division 2</td><td>Division 3</td>
    </tr>
  </table>

This also seems strange but not sure if it’s strictly wrong.

<pre><p>…</p></pre>

Remove `$margin` variable and add `$v-space` and `$h-space` in its place

$margin tends to get overused in weird places in our current system. Replacing this with a standardized vertical and horizontal spacing system should clarify usage a fair bit.

Consider including Sass Globbing

Separation of responsibilities is great. We can have each component live in a partial. However, it’s annoying to have to manually add imports for components (other things should still be manually imported). Sass-globbing neatly solves the issue. We should consider adding it to vellum and/or the adaptive generator.

Note: If we use Ruby Sass with Grunt, we can require Sass libs from the Grunt config. If we use libsass, this isn’t an option yet.

Leave default margins (zero) on input elements

Although we’ll always want spacing between form element, the variation in markup for forms (for different layouts at least) often requires different spacing rules and/or wrappers. This is a case where the best default for input, select and textarea is to leave default margins alone.

Use Bundler for Ruby gem dependencies

If we use any Ruby Gems, we should have a Gemfile to manage deps. This is another case of also determining how this fits with the Adaptive scaffold.

Change `document` to `global` so it can style for attribute selectors?

This issue is a continuation of the discussion started in #54.