Uno

For making internet.
[view source]

What is Uno?


Uno is a static-site generator and boilerplate, built with Gulp. It comes with Markdown, Sass and Babel baked-in. It also includes a dev server, lightweight HTML templating, linter support, image compression, and more.

Getting started


Uno requires:

Clone a new Uno, replacing APP_NAME with your own

$ git clone https://github.com/cincodesign/uno.git APP_NAME

Once you've cloned or downloaded the source, you simply need to run yarn install in that directory. Running yarn start will start a local development server at localhost:1337. Your default browser should open automatically. That's it. That's really it.

Scripts


Uno comes with a few built-in scripts out of the box. These are designed to streamline common workflows.

Script Description
yarn start Begins a local dev server, which will watch your code for changes and trigger the various 'gulp' scripts to run. Your browser will automatically reload when it's finished.
yarn test This will run eslint. Uno comes pre-configured with AirBnb's style guide and Prettier extensions. It's recommended you install the eslint plugin in your favorite text editor.
yarn imgmin This task will compress your jpg,png,gif, and svg files. It will squish a lot of bits out of your images, and this can have unintended consequences. It's left out of the main build scripts for a reason: use it wisely, and back up your stuff.
yarn build Before you hit the tubes, run yarn build. This'll minify your javascript and CSS and get everything tidy for production. All you need to do is throw your "build" folder up on the server and clock out. If you're using a service to deploy files, run this script on the server every time you push.

Custom Tasks

These scripts are just the tip of the iceberg. You can edit and extend these scripts yourself. We use Gulp for its simplicity and community support.

The gulpfile.babel.js directory houses all the gulp tasks, which are imported and referenced in that directory's index.js file. If you need to run any individual task, you'll need to install gulp globally via npm install -g gulp. Now you can run individual tasks like gulp styles or gulp copyfiles for debugging.

What's in the box


There are a lot of front-end tools in here. gulp and its numerous plug-ins, browserify with babelify that transpiles ES6 into code your browser can read, sass sprinkled with postcss. I'd be happy to explain how this all works over coffee, but for brevity's sake I'm gonna just hit the stuff that's going to get you rolling.

HTML


The main HTML file is source/html/index.html.

There's really lightweight templating built in utilizing gulp-file-include. By default it looks in the source/html/_includes directory. You can include any type file and it will spit out its contents:

Example: @@include('path/file.html') or @@include('path/logo.svg')

This handy plugin will also parse markdown files to HTML:

@@include(markdown('path/file.md')).

gulp-file-include has a bunch of great features, like @@for loops, and @@if conditionals, plus it even lets you loop over JSON data for advanced templating. It's best to read up on what it can do.

CSS


The entry file for you app's styles is source/styles/app.scss. CSS files get compiled from Sass.

Architecture

Your site's CSS contains a config file where you define site-wide globals. This lone file should be filled with variables that your entire site uses; things like colors, fonts, or transition timing. While there are many philosophies on CSS organization, we prefer to break stuff up into 5 sections: 'lib', 'core', 'components', 'sections' and 'pages'.

  • Lib – Lib contains some dependencies your app needs like mixins and functions, and top-level stuff like animation keyframes. It's also where the :root is located. It's a good idea to put anything here that might break if it goes missing.

  • Core – Core contains your base application selectors, naked stuff like body, p, or a tags. Really low-level stuff like basic typography selectors should go in here. The helpers file contains utility selectors.

  • Components – This is the meat of your app. Things like alerts, buttons, forms, headers, blockquote, you know. Any piece that is going to be very common and reusable.

  • Sections – This folder contains app sections. These might be global, like the header or footer, or appear on one or two pages, like a contact form. These typically make liberal use of components, but aren't quite as granular.

  • Pages – And finally, page specific CSS gets thrown into here.

Based.css Framework

Uno comes with the Based.css framework to jump start your site.

You can read the full documentation here.

Uno is extending Based a little bit. By default it imports the source and exposes some variables to configure, like grid sizing or spacing. These can be tweaked in the based file in source/styles.

Of course, you're not forced to use this framework. You can straight up delete it and reassign the variable names if you want to start super fresh. Uno's app.scss file will resolve paths from node_modules, so feel free to remove the dependency and use Bootstrap or Foundation or whatever you like.

Sass Utilities

Uno comes with a few cool utilities that make stylin' a little easier. You're welcome to extend them our pull in your favorite mixin library, like Bourban.

Postcss

On build, your styles takes a quick trip through postcss to automate some gotchas. We run autoprefixer so you can forgo writing vendor prefixes, pixrem to convert rem units to px as a fallback, and mqpacker to organize your media queries so you don't have to worry about duplicate queries causing cascading issues.

JavaScript


The main JS file is source/scripts/app.js.

We've baked in ES6 support (using Babel). ES6 JavaScript gets transpiled into browser-readable code. Read up on ES6 syntax and features.

You also have the ability to import modules and libraries (like jQuery) from npm instead of manually managing files yourself.

  • Install modules from npm in the command line: yarn add jquery. This install the script as a dependency.
  • Import these dependencies at the top of your JS files: import $ from 'jquery'
  • PLUS, you can import your own scripts: import component from './path/to/file'

The app.js file contains a super basic example.

I don't like things the way they are...

Hell, neither do I, but this is a good start. You can easily add more advanced templating like EJS, Jade, or Mustache, replace Based.css with Bootstrap, wire it up to use CoffeeScript if that's your thing, or create your own scripts.

Uno Sass Utils


Uno comes with a few Sass mixins and functions built-in.

Mixins


breakpoint

@include breakpoint([sm,md,lg,xl]) { ... }

When you need to make components or sections responsive, use the breakpoint() mixin. This mixin only accepts a breakpoint defined in src/scss/uno/_config.scss to insure consistency. If you need to specify a custom value, use a basic @media query. Out-of-the-box, Uno will consolidate all of your media queries with css-mqpacker on build.

maintain-aspect-ratio

@include maintain-aspect-ratio (16, 9);

This will force a component to maintain a certain aspect ratio, useful for embeded videos and stuff. Simply pass it two values like 16, 9 or 4, 3

font-size

@include font-size ([base,h1,h2,h3,h4,h5,sm]);

This ensures you use consistent font sizes throughout your app.

Functions


rem-calc

rem-calc(16px)

This will convert pixel values to rem because we're fancy. By default, 1rem = 16px, and things will scale with the $font-size variable in your config.

strip-unit

strip-unit($value)

This will strip the unit (px, em, vh, etc) from the value and return a plain number.