ZURB Foundation Building Blocks

Piece together amazing sites faster with Foundation Building Blocks. ZURB Building Blocks is a pattern library for Foundation UI components. These HTML, CSS, and JS snippets can be plugged into any Foundation project to build faster. Enjoy!

What is a Building Block?

Building Blocks are coded UI components designed to be dropped into Foundation projects. Many Building Blocks are based on tried and true patterns that we’ve used in our client projects over the last five years using Foundation.

Building Blocks are:

Code that works in any Foundation project (matching version)
Lightly styled components
Easy to extend or customize
Common solutions to layout or component challenges that are not core to the Framework

A Building Block is NOT:

A template
A theme
A place to dump code
Overly stylized

We want these to be code you can add to your website to solve common patterns, build faster, and integrate with your existing styles.

How to use a Building Block

Building Blocks are easy to use in your projects whether you’re using a CSS version or the powerful ZURB Stack. Below, we’ve outlined how to get a Building Block into your project in a snap and build faster.

Copy it

Like a Building Block? You can copy the HTML and CSS/SCSS and JS (if applicable) from the Building Block detail page. You’ll see a responsive preview and any relevant information at the top of the page. Below the preview you’ll find the code for the component.

The HTML, CSS, and JS toggles let you focus on one section at a time if you’d like.

You can copy the the code from each code container using the handy copy button.

If you are using CSS vs SCSS, you can toggle to the compiled CSS using this handy toggle:

If you’re using the CSS version of Foundation, it’s best to add the CSS to your app.css file that is included with the downloaded Foundation CSS project. You can make any style overrides from there.

If you’re using the ZURB Stack Sass version, a custom SCSS partial is the best place to add the Building Block’s SCSS. The JS can be added to app.js. But if you’re a fan of optimization, we suggest you use the Foundation CLI install to do all this automatically for you.

Download a kit

Looking to start with a Building Block kit? Kits are large collections of Building Blocks that are matched to each other for a specific type of Site, App, or use case. To save you time over the copy/paste method of individual Building Blocks, you can download a zip file of the kit. For each Building Block, it will come with:

Individual HTML files
Individual CSS files for each
Individual SCSS files in case you want to manually add them to a Sass project
Individual JS files (if applicable)

Again, if you’re using the ZURB Stack, the Foundation CLI can do this for you. Find out how below.

Foundation CLI Install

This is where a powerful workflow like the ZURB Stack really ups your game. You want to add a Building Block to your project to show an interaction or build a page in record time. Imagine if you could add a Building Block or even an entire kit of Building Blocks to your site with a single command. You don’t have to imagine because an update to the Foundation CLI allows you to do just that.

Foundation’s CLI install will:

Create you a Panini HTML partial with the Building Block’s HTML
Create you a SCSS partial with the Building Block’s SCSS and also add the @import for you in your app.scss file.
Create you an JS file with the Building Block’s JS and link it up in the config.yml

Bam! Add your Panini include on your page or layout and you’re ready to rock.

In your terminal, make sure you’re in you ZURB Stack project.

The available commands are: foundation blocks list - List out the names of all the available Building Blocks. It’s a lot! foundation blocks install [blockname] - installs an individual Building Block foundation kits list - List out the names of all the available Building Block kits. foundation kits install [kitname] - installs all the Building Blocks in the kit

Dependencies

Building Blocks are made to drop into any Foundation project and work. Therefore Foundation is a dependency (needs it to work as expected).

Since Foundation’s interactive components are build using jQuery, jQuery is a dependency. Every Foundation download or Install comes with this. jQuery is not required for CSS/SCSS only components or non-js components in Foundation.

Some Building Blocks use icon fonts to make them look nicer or convey intention. You can use the same icon fonts by adding them to your project. You can download FontAwesome icons here: http://fontawesome.io/

Or add this CDN to the head of your pages or layout: <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.css" rel="stylesheet">

How to Submit a Building Block

So you want to build a Building Block? Well fear not! You can get in on the action too and get your work featured! We’ve put together a simple guide to submitting a Building Block. Once it’s submitted, we’ll promote your awesomeness to the greater Foundation community because you rock!

What Do I Need to Submit A Building Block?

The Building Blocks site is open source just like Foundation, meaning anyone can contribute to it. It’s built on the same Node based build system the ZURB Stack is built on. Submissions are made through GitHub, with pull requests.

You’ll need:

A sweet Building Block A GitHub account

Your computer needs:

NodeJS (6.10.1) You can clone or download the repo from here: https://github.com/zurb/building-blocks

Using your terminal, change directory into the building-blocks project and run

npm install then
bower install

Once the install is complete, in the project directory, you can start the project and have it watch for changes. Run: npm start

This will start the build system and watch for changes. When you save a change, the browser preview will refresh automatically. That’s it for setup!

Submitting your Building Block

There are just a few simple files needed to submit your Building Block.

HTML: Every Building Block will need an HTML file to demonstrate the uniqueness of the component or layout.
SCSS: You’ll add your custom styles in a SCSS file. You only need your additional styles as Foundation is already being imported for you.
JS: If your component uses custom JavaScript/jQuery you’ll create a JS file and add it there. Again, Foundation JS and jQuery are already included, so only your addition JS is needed if you used any.
Image: A preview image of your Building Block. This will help people get excited about the awesome work you do! See suggestions for great preview images. The should be in a .png format.
yml: You’ll want to describe your Building Block and submit your name. A Yaml file uses a .yml file extension and is where the Building Block name, description, tags and more are stored.

You’ll find the building-blocks folder in the root directory of the Building Blocks project. This is where all the Building Blocks that get displayed on the site live.

Step 1:

Create a branch from which to submit your Building Block from. This will allow you to submit a Pull Request when you’re done so that the Foundation team can review it, offer suggestions and merge it in. In your terminal, checkout a new branch git checkout -b your-branch-name

Step 2:

Create a new folder in the Building Blocks folder. Name it the name of your Building Block. The name should contain the component or type of component it is. For example a card should have Card in the name or a sidebar layout should have Sidebar in the name.

Example: article-card All your files in the folder will have the same root name

article-card
- article-card.html
- article-card.scss
- article-card.js
- article-card.png
- article-card.yml

Step 3:

In your Building Block component folder, create your .html, .scss, .js and .yml pages.

Create a HTML file

Example: article-card.html
Paste in your HTML
Save

Create an SCSS file

Example: article-card.scss
Paste in your SCSS or CSS
Save

Create an JS file (if applicable)

Example: article-card.js
Paste in your JS
Save

Create an YML file

Example: article-card.yml
Add in your Building Block information
Save

Here is a .yml file template you can use:

name: 'Short title description'
tags:
  - media
  - blog
  - card
  - animation
category: container
description: Longer description about Building Block, settings, use cases, classes to modify or additional important info.
versions:
  - 6.3.1
  - 6.3.0
author:
  name: Your name
containerClass: container-padded row medium-5 large-3 column

Add your image to your component’s folder

Example: article-card.png
Add the image to the article-card folder for this example

That’s it!

You can preview your new Building Block on the homepage or go directly to it. Example URL: http://localhost:8000/building-block/article-card/article-card.html

Looking good?

Step 4:

Now it’s time to submit your Building Block. Make sure to add and commit your work. The submit your Pull Request.

Review Process

Once you submit your Building Block pull request, a member of the Foundation team will review it to add it in.

Thing we’ll be looking for:

An image
The Building Block meets class naming guidelines
The Building Block works well on all screen sizes
The .yml file has the proper tags and description.

We'll comment on a the code through GitHub to ask for changes or to let you know it's been added in.

Container Classes

In order to make sure the Building Block preview is presented well, you can specify container classes to align the content. Here is breakdown of these classes:

Helper classes:

container-padded: adds 1rem top-padding above your Building Block to space it down from the top of the container. Most components will use this. You may leave it out for a component that should be flush with the top like a navigation.
align-center: this will align a Building Block or columns horizontally in the center of the page.
text-center: This is useful to align buttons horizontally in the center.

Grid classes:

You can also use grid classes to constrain the width of your Building Block. This helps keep the markup of the Building Block clean of extraneous markup.

Example: containerClass: container-padded row medium-5 large-3 column

Submitting a Good Preview Image

Class Naming

Installation

To use this template, your computer needs:

NodeJS (0.12 or greater)
Git

Manual Setup

To manually set up the template, first download it with Git:

git clone https://github.com/zurb/building-blocks.git

Then open the folder in your command line, and install the needed dependencies:

cd building-blocks
npm i
bower i

Finally, run npm start to start the project and watch for changes. It will open in your browser at:

http://localhost:8000

To deploy, run npm run deploy.

brettsmason / building-blocks