Clank Documentation

What is Clank?

Clank is an open source prototyping framework for mobile apps. Think of it as Twitter Bootstrap but for prototyping native apps.


Why Clank?

Actually looks like a native app

We strive to actually look like a native app (as far as web tech allows us to go) instead of pseudo implementations.

Component based: pick and choose

Clank is a collection of HTML/CSS components. For example, a button is a component. It has it's own SCSS file: components/_button.scss.

Every component stands on its own and can't influence other components. Clank has strong rules on component naming to avoid any style clashes.

A good component only defines layout and provide hooks for specific looks.

We strive to actually look like a native app (as far as web tech allows us to go) instead of pseudo implementations.


Skinning-mechanism

Clank uses variables in SCSS to provide an easy way to easily change the look of Clank-made applications.

Changing the global color of headers, bars and buttons is as easy as changing one variable:

$accent-color: red;

Variables for cross platform design

Every operating system has its own look and feel. Clank acknowledges that you are building apps for multiple platforms. We see each part of the design as a variable that can be altered:

$functional-shadows: true;
$decorational-shadows: false;

Sometimes in more detail:

$border-radius: 4px;

This way, it's easy to generate an iOS or Android specific style sheet by switching out the variables. Or maybe you want to create a unified look that looks like your brand instead of chasing platform guidelines. It's all possible.

You also want to switch on a functional level i.e. you might want to swap out an iOS header for an Android action bar component. More on this in component includes.

Philosophy

You should try to make your application using standard components. The standard components used in iOS and Android have a lot of work behind them. Face it, you don't have 2 weeks to perfect a <select>.


Device wraps

What are device wraps?

Device wraps — like the ones you see in the demos — are "fake" representations of devices. This allows you to develop in your preferred web development environment (i.e. in my case Google Chrome with LiveReload on) while still getting a good preview of what it might look like on a real device. Think of the device frames as the iOS/Android simulator, brought to your browser.

One possible use case for the wraps frames is to present design work to a client in a meeting.

Presenting work on real devices

If you want to present your work on a real device (and you should) switch the $device-wraps variable to false in _vars.scss. This will disable all CSS related to device wraps.


Browser support

It's not advisable to use Clank for production work since it only supports new and modern browsers like Google Chrome, Firefox and Safari. A lot of the techniques used in Clank depend on newer CSS properties such as Flexbox. For now, Clank is a prototyping tool and testbed for modern web technologies.


(S)CSS conventions

We use SCSS for all CSS because it provides us with a way to extend CSS with variables and mixins.

Every component should be prefixed with cl-:

.cl-accordion { }

This is verbose but the only way to not clash with other libraries until Web Components are commonplace.

A child element dependent on the component should be added with a hyphen:

.cl-accordion-item { }

State should be added with a double underscore:

.cl-accordion-item__disabled { }

This prevents too many nested selectors in SCSS.

This naming technique has been coined BEM.


(S)CSS commenting

Commenting is done in this style:

/* ==========================================================================
   Section comment block --> Mostly for components
   ========================================================================== */

/* Sub-section comment block --> For parts of components
   ========================================================================== */

/* Basic comment */

Inspired by Idiomatic CSS.


Starter templates

These are some templates to help you get started. Copy/paste this code in the body of your .html files to see the results.

Empty iOS styled page

<div data-os="ios">
  <!-- Change data-os to android to switch to an Android look -->
  <div class="cl-page">
    <div class="cl-bar-title">
      <h1 class="cl-title">Getting started!</h1>
    </div>
    <div class="cl-content">
      <div class="cl-article">
        <p>Put your article content here.</p>
      </div>
    </div>
  </div>
</div>

Page with iPhone 4 device wrap

Make sure $device-wraps is set to true.

<div class="cl-device-frame">
  <div class="cl-device-wrap" data-os="ios" data-device="iphone4-portrait">
    <div class="cl-device-body">
      <div class="cl-ios-status">
        <span>
        <span class="signals">
          <span class="signal1"></span>
          <span class="signal2"></span>
          <span class="signal3"></span>
          <span class="signal4"></span>
          <span class="signal5"></span>
        </span>
        <span class="carrier">Bell</span>
        </span>
        <span class="clock">20:49</span>
        <span>
        <span>3G</span>
        <span class="icon-ios-alarm"></span>
        <span class="icon-ios-locate"></span>
        <span class="icon-ios-lock"></span>
        <span class="icon-ios-battery"></span>
        </span>
      </div>

      <div class="cl-page">
        <div class="cl-bar-title">
          <h1 class="cl-title">App title</h1>
        </div>
        <div class="cl-content">
          <!-- Content here -->
        </div>
        <div class="cl-bar-footer">
          <!-- Footer content here -->
        </div>
      </div>
    </div>
  </div>
</div>

Page with galaxy nexus device wrap

Make sure $device-wraps is set to true.

<div class="cl-device-frame">
  <div class="cl-device-wrap" data-os="android" data-device="galaxynexus-portrait">
    <div class="cl-device-body">
      <div class="cl-android-status">
        <span>
        <span class="icon-android-battery"></span>
        <span class="icon-android-network"></span>
        <span class="icon-android-wifi"></span>
        <span>20:49</span>
        </span>
      </div>
    
      <div class="cl-android-software-buttons">
        <span>
        <span class="icon-android-system-back"></span>
        <span class="icon-android-system-home"></span>
        <span class="icon-android-system-apps"></span>
        </span>
      </div>

      <div class="cl-page">
        <div class="cl-bar-title">
          <h1 class="cl-title">App title</h1>
        </div>
        <div class="cl-content">
          <!-- Content here -->
        </div>
        <div class="cl-bar-footer">
          <!-- Footer content here -->
        </div>
      </div>
    </div>
  </div>
</div>

Clank: future plans

These are some of the future plans, most are related to a better workflow. If you are interested in working on these check out the issues on Github.

Grunt + Jekyll based workflow

A grunt workflow for Clank projects with automatic tasks:

grunt Default action - compiles Compass, Jekyll, does automatic Livereload. This is what you to use the work on the application.
grunt dist Creates a build for distribution - optimizes the CSS files and images. Concatenates and minified the JS. Allows you to generate a CSS file targetd at a single platform (for CSS optimization purposes)

Automatic icon fonts

Using fontcustom and a grunt workflow, any .svg files within a specific folder will automatically be transformed to an icon font you can use in your Clank projects.


Generators

Note that generators are a work in progress and they do not exist yet. If you are good at bash scripting and interested in working in generators, get in touch.

What is a generator?

A generator is simply a bash script that generates code for you. This makes it easy to, for example, add new screens or components to your project.

Possible generators

generate-page.sh Creates a new page and its corresponding SCSS files.
generate-component.sh Creates a new component and its corresponding SCSS files.

Component includes

Component includes is a planned feature where you can swap components in your prototypes depending on the operating system. E.g. for your Android application you might want to use Android style tabs, but the same functionality in the iOS version uses a segmented control.