Stylus-UI

A minimalist Stylus boilerplate

Get Started

Why use Stylus-UI

Stylus-UI provides a minimal setup of styles for a fast and clean starting point. Specially designed for better performance and higher productivity with fewer properties to reset resulting in cleaner code. No framework, just a solid starting point using some conventions & functional classes we've established over the years at Clock.

Getting Started

Stylus-UI provides minimal styles for you to get started with your project and so to ensure that you are never fighting the boilerplate trying to customise it or override styles, we recommend that you download the .zip file and place the extracted files in your project.

For compilation we've included a gulpfile.js which compiles assets/styles/stylus-ui.styl by default and outputs the compiled assets to public/assets/main.css and public/assets/main.min.css. You should add a CSS Reset in the header of your project (normalize is a good choice, see the example below), then add the Stylus-UI compiled stylesheet after the CSS Reset. Once downloaded and placed within your project, please follow the instructions below.

Download Stylus-UI

Install dependencies

If you have an existing package.json in your project, you should install the dev-dependencies listed below. If not, you can use the package.json included with Stylus-UI and simply run npm i to install all required dependencies.

// Ensure that Gulp is installed globally
$ npm install -g gulp

// Install the Stylus-UI dependencies & add to package.json
npm i --save-dev gulp-stylus gulp-sourcemaps gulp-autoprefixer gulp-cssnano gulp-plumber gulp-clean gulp-watch gulp-rename gulp-size gulp-notify gulp-exec

Usage

Add these tags in the head of your layout.

<!-- Google Fonts -->
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300italic,700,700italic">

<!-- CSS Reset -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/normalize/3.0.3/normalize.css">

<!-- Stylus-UI CSS minified -->
<link rel="stylesheet" href="/public/styles/main.min.css">

<!-- You should properly set the path to main.min.css -->

Mixins

Stylus-UI uses Stylus-Mixins to make working with certain CSS elements easier. The mixins you're most likely to use the most are rem() and the media query mixins.

REM

Instead of working with px values, simply pass the pixel value to the rem mixin. We set the $base--font-size in settings.styl and apply it the the html element in foundations/_base.styl. By using rem through-out your project, you ensure that property values are set relative to the base font size.

.navigation-item
  font-size rem(12)
Media Queries

Stylus-UI takes a mobile first approach to responsive design, so should you need to adjust styles for tablet or desktop, you will need to use The Media Query Grid. Fortunately we've made this considerably easier for you. The settings for media queries and breakpoints reside in settings.styl, and the grid is constructed in _grid.styl. We highly encourage you to modify these files to suit your own project.

.navigation-item
  color $color--primary
  font-size rem(12)

  // adjust the font size for tablet up
  +width-min($mq--tablet)
    font-size rem(14)

  // adjust the font size for desktop up
  +width-min($mq--desktop)
    font-size rem(16)

  // adjust the font color for tablet only using the range mixin
  +width-range($mq--tablet, $mq--desktop -1)
    color $color--secondary

The Grid

The Grid is a fluid system with a max width of 1280px that shrinks with the browser/device at smaller sizes. The max width can be changed by adjusting the $base--max-width variable in foundations/_settings.styl and all columns will resize accordingly. The grid utilises Flexbox and takes a mobile-first approach. Simply add columns you want in a row, and they'll evenly take up the available space. If you want three columns, add three columns, if you want five columns, add five columns. There is no restriction on number of columns, but we advise you to use your common sense. We follow BEM conventions for column modifiers as shown below.

Please note, that since the grid takes a mobile first approach, each breakpoint inherits from the previous breakpoint. For example, if you modify the grid size at a specific breakpoint, all larger breakpoints will inherit this modification. So if you modify the grid for tablet, think of it as modifying the grid for tablet and up.

// Mobile will span 100%. Tablet and desktop (and any larger breakpoints) will span 50%.
column column--50-tablet

If you intend to target a specific breakpoint and modify its grid only, simply append -only to your grid modifier. For example, if we wanted all sections to span 100% of the screen, but only tablet should span 50%, our classes would look like column column--50-tablet-only. Now mobile and desktop would span 100%, but tablet would only span 50%.

.column
.column
.column
.column
.column
.column.column--50.column--offset-25

Nested Grids

.column
.column
.column
.column
.column
.column
.column.column--50.column--offset-25
.column
.column
.column
.column
.column
.column
.column.column--50.column--offset-25

Media Query Grid

.column.column--50-tablet
.column.column--50-tablet-only
.column.column--75-mobile-only.column--50-tablet

Typography

CSS3 introduces a few new units, including the rem unit, which stands for "root em". The rem unit is relative to the font-size of the root element <html>. That means that we can define a single font size on the root element, and define all rem units to be a percentage of that. The typography has font-size defined in 1.6rem (16px) and line-height in 1.6 (24px). stylus-ui uses the font-family Roboto, created by Christian Robertson, and provided by Google.

Heading <h1> 5.0rem (50px)

Heading <h2> 4.2rem (42px)

Heading <h3> 3.6rem (36px)

Heading <h4> 3.0rem (30px)

Heading <h5> 2.4rem (24px)
Heading <h6> 1.5rem (15px)
<!-- Base font-size and line-height -->
<p>The base type is 16px over 1.6 line height (24px)</p>

<!-- Other elements to text markup -->
<a>Anchor</a>
<em>Emphasis</em>
<small>Small</small>
<strong>Strong</strong>
<u>Underline</u>

<!-- Default Headings -->
<h1>Heading</h1>
<h2>Heading</h2>
<h3>Heading</h3>
<h4>Heading</h4>
<h5>Heading</h5>
<h6>Heading</h6>

Buttons

The Button, an essential part of any user experience. Buttons come in three basic styles in stylus-ui: The <button> element has flat color by default, whereas .button--outline has a simple outline around, and .button--clear is entirely clear.

<!-- Standard buttons -->
<a class="button" href="#">Anchor button</a>
<button>Button element</button>
<input type="submit" value="submit input">
<input type="button" value="button input">

<!-- Primary buttons -->
<a class="button button--outline" href="#">Anchor button</a>
<button class="button--outline">Button element</button>
<input class="button--outline" type="submit" value="submit input">
<input class="button--outline" type="button" value="button input">

Forms

The Form has never been exactly fun, and it can be downright painful on a mobile device with its on-screen keyboard. stylus-ui help to make this much easier with design focused on the user experience.

<form>
  <fieldset>
    <label for="nameField">Name</label>
    <input type="text" placeholder="Niall O'Brien" id="nameField">
    <label for="commentField">Comment</label>
    <textarea placeholder="Hi there …" id="commentField"></textarea>
    <div class="example-send-yourself-copy">
      <input type="checkbox" id="confirmField">
      <label class="label-inline" for="confirmField">Send a copy to yourself</label>
    </div>
    <input type="submit" value="Send">
  </fieldset>
</form>

<!-- Always wrap checkbox and radio inputs in a label and use a <span class="label-inline">
      inside of it -->

Lists

The List is a very versatile and common way to display items. stylus-ui has three types of lists: The unordered list use <ul> element will be marked with a outline circles, the ordered list use <ol> element and your items will be marked with numbers, the description list use <dl> element and your items will not be marking, only spacings.

  • Unordered lists have basic styles
  • They use the circle list style
    • Nested lists styled to feel right
    • Can nest either type of list into the other
  • Just more list items
  1. Ordered lists also have basic styles
  2. They use the decimal list style
    • Ordered and unordered can be nested
    • Can nest either type of list into the other
  3. Last list item just for the fun
<!-- Unordered list -->
<ul>
  <li>Unordered list item 1</li>
  <li>Unordered list item 2</li>
</ul>

<!-- Ordered list -->
<ol>
  <li>Ordered list item 1</li>
  <li>Ordered list item 2</li>
</ol>

<!-- Description list -->
<dl>
  <dt>Description list item 1</dt>
  <dd>Description list item 1.1</dd>
</dl>

<!-- Easily change any <dl>, <ul> or an <ol> to get clear lists, 
      number lists or outline circles. -->

Code

Code styling is kept basic – just wrap anything in a <code> and it will appear like this. For blocks of code, wrap a <code> with a <pre>.

.navigation-item
  color #9b4dca
<pre><code>
.navigation-item
  color #9b4dca
</code></pre>

Blockquotes

The Blockquote represents a section that is quoted from another source.

Stylus-UI is pretty cool.

<blockquote>
  <p><em>Stylus-UI is pretty cool.</em></p>
</blockquote>

Tables

The Table element represents data in two dimensions or more. We encourage the use of proper formatting with <thead> and <tbody> to create a <table>. The code becomes cleaner without disturbing understanding.

Name Age Height Location
Stephen Curry 27 1,91 Akron, OH
Klay Thompson 25 2,01 Los Angeles, CA
<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Age</th>
      <th>Height</th>
      <th>Location</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Stephen Curry</td>
      <td>27</td>
      <td>1,91</td>
      <td>Akron, OH</td>
    </tr>
    <tr>
      <td>Klay Thompson</td>
      <td>25</td>
      <td>2,01</td>
      <td>Los Angeles, CA</td>
    </tr>
  </tbody>
</table>
  

Utilities

Stylus-UI has some functional classes to improve the prototype productivity.

Typography

.font-family-inherit
.font-size-inherit
.text-decoration-none
.bold
.regular
.italic
.caps
.left-align
.center
.right-align
.justify
.nowrap
.break-word
.line-height-default
.line-height-1
.line-height-2
.line-height-3
.line-height-4
.list-style-none
.underline
.truncate
.list-reset

Layout

.inline
.block
.inline-block
.table
.table-cell
.overflow-hidden
.overflow-scroll
.overflow-auto
.clearfix
.left
.right
.fit
.max-width-1
.max-width-2
.max-width-3
.max-width-4
.border-box

Align

.align-baseline
.align-top
.align-middle
.align-bottom

Margin & Padding

m = margin, p = padding. t = top, r = right, b = bottom, l = left, x = horizontal, y = vertical. 0 - 4 = smallest - largest.

.m0
.mt0
.mr0
.mb0
.ml0
.mx0
.my0

.m1
.mt1
.mr1
.mb1
.ml1
.my1
.mx1
etc.
etc.
.my4
.mx4
.p0
.pt0
.pr0
.pb0
.pl0
.px0
.py0

.p1
.pt1
.pr1
.pb1
.pl1
.py1
.px1
etc.
etc.
.py4
.px4

Borders

.border
.border-top
.border-right
.border-bottom
.border-left
.border-none

.rounded
.circle
.rounded-top
.rounded-right
.rounded-bottom
.rounded-left
.not-rounded

Position

.relative
.absolute
.fixed

.top-0
.right-0
.bottom-0
.left-0

.z1
.z2
.z3
.z4

Hide

Mobile first, breakpoints assume screen-size and up much like the grid. Eg. .hide-tablet = .hide-tablet-and-up.

.hide
.hide-mobile-only
.hide-tablet
.hide-tablet-only
.hide-desktop
.display-none

Colors

For background colors, prefix with 'bg-', eg. .bg-red.

For border colors, prefix with 'border-', eg. .border-red. Ensure you add .border first.

.black
.gray
.silver
.white

.aqua
.blue
.navy
.teal
.green
.olive
.lime

.yellow
.orange
.red
.fuchsia
.purple
.maroon

.color-inherit
.muted

Darken / Lighten

.bg-darken-1
.bg-darken-2
.bg-darken-3
.bg-darken-4

.bg-lighten-1
.bg-lighten-2
.bg-lighten-3
.bg-lighten-4

Background Images

.bg-cover
.bg-contain

.bg-center
.bg-top
.bg-right
.bg-bottom
.bg-left

.bg-no-repeat
.bg-repeat-x
.bg-repeat-y
Browser Support

While not designed for old browsers, stylus-ui has support for some old versions, but we recommend using the latest versions of their browsers.