Prototype iPhone apps with simple HTML, CSS and JS components.

Download Ratchet

Getting started

Once you've downloaded Ratchet, here's what to do next.

  1. 1. Create your pages

    Use these docs as a reference for all the available components and piece together the pages of your app. Customize the style too - make the prototype all your own.

  2. 2. Connect pages with push.js

    Read about push.js then start connecting your pages. Push.js allows you to create a prototype that feels like a real app when you save it to your phone. (Need to have a server running).

  3. 3. Save the prototype to your phone

    There are a few ways to do this, but the simplest is to run a local server on your computer, point Safari on your iPhone to your computer, then click the button and "Add to Home Screen".

Heads up! Ratchet components are written only for iPhone, so many are broken in non-Webkit browsers.

Components

Design patterns that serve as basic building blocks.

Title

Title bar

Title bars are full width and docked to the top of the viewport.

Title

<header class="bar-title">
  <h1 class="title">Title</h1>
</header>

Title bar with buttons

Buttons in a title bar are left or right aligned and should be used for actions.

<header class="bar-title">
  <a class="button" href="#">
    Left
  </a>
  <h1 class="title">Title</h1>
  <a class="button" href="#">
    Right
  </a>
</header>

Title bar with directional buttons

Directional buttons in a title bar should be used for navigational purposes.

<header class="bar-title">
  <a class="button-prev" href="#">
    Previous
  </a>
  <h1 class="title">Title</h1>
  <a class="button-next" href="#">
    Next
  </a>
</header>

Title bar with segmented controller

Title bars can also house segmented controllers (with or without accompanying buttons). It all uses flex-box to create perfectly even spacing no matter their labels.

<header class="bar-title">
  <a class="button" href="#">
    Left
  </a>
  <ul class="segmented-controller">
    <li class="active">
      <a href="#">One</a>
    </li>
    <li>
      <a href="#">Two</a>
    </li>
    <li>
      <a href="#">Three</a>
    </li>
  </ul>
  <a class="button" href="#">
    Right
  </a>
</header>

Tab bar

Icons should be around 24px by 18px. The gradient on an icon starts with pure white and goes to #e5e5e5 at the bottom.

<nav class="bar-tab">
  <ul class="tab-inner">
    <li class="tab-item active">
      <a href="">
        <img class="tab-icon" src="img/icon-home.png">
        <div class="tab-label">Label</div>
      </a>
    </li>
    <li class="tab-item">
      <a href="">
        <img class="tab-icon" src="img/icon-profile.png">
        <div class="tab-label">Label</div>
      </a>
    </li>
    <li class="tab-item">
      <a href="">
        <img class="tab-icon" src="img/icon-messages.png">
        <div class="tab-label">Label</div>
      </a>
    </li>
    <li class="tab-item">
      <a href="">
        <img class="tab-icon" src="img/icon-hamburger.png">
        <div class="tab-label">Label</div>
      </a>
    </li>
    <li class="tab-item">
      <a href="">
        <img class="tab-icon" src="img/icon-settings.png">
        <div class="tab-label">Label</div>
      </a>
    </li>
  </ul>
</nav>

Note: Use push.js to actually change content.

Credit: Icons by Marc Haumann and Spencer Cohen from The Noun Project

Standard bars

Standard bars are basic fixed elements that can be positioned in 3 places. These can be used to house buttons or segmented controllers (see following examples).

<!-- Segmented controller in standard bar fixed to top -->
<nav class="bar-standard">
  <ul class="segmented-controller">
    <li class="active">
      <a href="#">Thing one</a>
    </li>
    <li>
      <a href="#">Thing two</a>
    </li>
    <li>
      <a href="#">Thing three</a>
    </li>
  </ul>
</nav>
<div class="bar-standard bar-header-secondary">
  <a class="button-block">Block level button</a>
</div>

Lists

Lists can be used for organizing data, showing collections of links or a series of controls.

  • List item 1
  • List item 2
  • List Divider
  • List item 3
<ul class="list">
  <li>List item 1</li>
  <li>List item 2</li>
  <li class="list-divider">List Divider</li>
  <li>List item 3</li>
</ul>

List with chevrons

Chevrons are created with CSS3, so no image assets are needed. They should be used to indicate that the list item is linked.

<ul class="list">
  <li>
    <a href="#">
      List item 1
      <span class="chevron"></span>
    </a>
  </li>
  <li>
    <a href="#">
      List item 2
      <span class="chevron"></span>
    </a>
  </li>
  <li>
    <a href="#">
      List item 3
      <span class="chevron"></span>
    </a>
  </li>
</ul>

List with counts

  • List item 1 4
  • List item 2 1
  • List item 3 5
<ul class="list">
  <li>List item 1 <span class="count">4</span></li>
  <li>List item 2 <span class="count">1</span></li>
  <li>List item 3 <span class="count">5</span></li>
</ul>

List with counts and chevrons

<ul class="list">
  <li>
    <a href="#">
      List item 1
      <span class="chevron"></span>
      <span class="count">4</span>
    </a>
  </li>
  <li>
    <a href="#">
      List item 2
      <span class="chevron"></span>
      <span class="count">1</span>
    </a>
  </li>
  <li>
    <a href="#">
      List item 3
      <span class="chevron"></span>
      <span class="count">5</span>
    </a>
  </li>
</ul>

List with buttons

<ul class="list">
  <li>List item 1 <a class="button">Button</a></li>
  <li>List item 2 <a class="button-main">Button</a></li>
  <li>List item 3 <a class="button-positive">Button</a></li>
  <li>List item 4 <a class="button-negative">Button</a></li>
</ul>

List with toggles

  • List item 1
  • List item 2
  • List item 3
<ul class="list">
  <li>
    List item 1
    <div class="toggle">
      <div class="toggle-handle"></div>
    </div>
  </li>
  <li>
    List item 2
    <div class="toggle active">
      <div class="toggle-handle"></div>
    </div>
  </li>
  <li>
    List item 3
    <div class="toggle">
      <div class="toggle-handle"></div>
    </div>
  </li>
</ul>

Inset list

  • List item 1
  • List item 2
  • List Divider
  • List item 3
  • List item 4
<ul class="list inset">
  <li>List item 1</li>
  <li>List item 2</li>
  <li class="list-divider">List Divider</li>
  <li>List item 3</li>
  <li>List item 4</li>
</ul>

Buttons

Buttons come in four flavors and should be used for user actions.

<a class="button">Button</a>
<a class="button-main">Button</a>
<a class="button-positive">Button</a>
<a class="button-negative">Button</a>

Buttons with counts

<a class="button">Count button<span class="count">1</span></a>
<a class="button-main">Count button<span class="count">1</span></a>
<a class="button-positive">Count button<span class="count">1</span></a>
<a class="button-negative">Count button<span class="count">1</span></a>

Block buttons

<a class="button-block">Block button</a>
<a class="button-main button-block">Block button</a>
<a class="button-positive button-block">Block button</a>
<a class="button-negative button-block">Block button</a>

Segmented controller

Created with flex-box so button sizes and spacing are consistent. Content sections that are to be swapped in and out by the controller should all be siblings and have the class "segmented-controller-item". Then, just give each content section an id and point the link in the segmented controller to that id.

  • Item 1
  • Item 2
  • Item 3
<ul class="segmented-controller">
  <li class="active">
    <a href="#item1">Thing one</a>
  </li>
  <li>
    <a href="#item2">Thing two</a>
  </li>
  <li>
    <a href="#item3">Thing three</a>
  </li>
</ul>
<ul class="inset list">
  <li id="item1" class="segmented-controller-item active">
    Item 1
  </li>
  <li id="item2" class="segmented-controller-item">
    Item 2
  </li>
  <li id="item3" class="segmented-controller-item">
    Item 3
  </li>
</ul>

Counts

Counts come in four flavors and should be used to indicate "how many" of something there are.

1 2 3 4
<span class="count">1</span>
<span class="count-main">2</span>
<span class="count-positive">3</span>
<span class="count-negative">4</span>

Forms

<form>
  <input type="text" placeholder="Full name">
  <input type="search" placeholder="Search">
  <textarea rows="5"></textarea>
  <a class="button button-block">Choose existing</a>
</form>

Form with input group

<form>
  <div class="input-group">
    <input type="text" placeholder="Full name">
    <input type="email" placeholder="Email">
    <input type="text" placeholder="Username">
  </div>
</form>

Form with input group and labels

<form>
  <div class="input-group">
    <div class="input-row">
      <label>Full name</label>
      <input type="text" placeholder="Mister Ratchet">
    </div>
    <div class="input-row">
      <label>Email</label>
      <input type="email" placeholder="ratchetframework@gmail.com">
    </div>
    <div class="input-row">
      <label>Username</label>
      <input type="text" placeholder="goRatchet">
    </div>
  </div>
</form>

Toggles

Toggles can be used by sliding or tapping the control.

<div class="toggle active">
  <div class="toggle-handle"></div>
</div>
<div class="toggle">
  <div class="toggle-handle"></div>
</div>

Toggles.js binds an event to the document that returns a detail object and can be used to fire a callback.

// Only needed if you want to fire a callback
document
  .querySelector('#myToggle')
  .addEventListener('toggle', myFunction)

Popovers

Left

Popover title

Right
  • Item1
  • Item2
  • Item3
  • Item4
<div id="myPopover" class="popover">
  <header class="popover-header">
    <a class="button" href="#">
      Left
    </a>
    <h3 class="title">Popover title</h3>
    <a class="button" href="#">
      Right
    </a>
  </header>
  <ul class="list">
    <li>Item1</li>
    <li>Item2</li>
    <li>Item3</li>
    <li>Item4</li>
  </ul>
</div>

Popovers are designed to only fire from title bars. Set the value of the title href to the id of a popover, like so:

<header class="bar-title">
  <a href="#myPopover">
    <h1 class="title">Title</h1>
  </a>
</header>

Sliders

Can be used with any number of slides with any type of content.

  • ← Slide me
<div class="slider">
  <ul>
    <li>
      <img src="img/slide-1.jpg">
      <span class="slide-text">← Slide me</span>
    </li>
    <li>
      <img src="img/slide-2.jpg">
    </li>
    <li>
      <img src="img/slide-3.jpg">
    </li>
  </ul>
</div>

Sliders.js binds an event to the document that returns a detail object and can be used to fire a callback.

// Only needed if you want to fire a callback
document
  .querySelector('#mySlider')
  .addEventListener('slide', myFunction)

Push

Push.js is the engine that connects Ratchet pages together with AJAX and the history api. Push.js is listening to all clicks on a page, so just make sure it's included and link something in your Ratchet project up.

<!-- A one.html link -->
<a href="two.html">Two<a>

This will use push to replace everything in the .content div with the .content of two.html. It will also update .bar-title and .bar-tab if you have them on both pages.

Now that pages are being loaded through push, it's easy to specify transitions for animations between pages. There are three different transitions to chose from: fade, slide-in, or slide-out.

<!-- An one.html link that animates to two.html -->
<a href="two.html" data-transition="fade">Two<a>

A working version of push:

<header class="bar-title">
  <h1 class="title">Push</h1>
</header>
<div class="content">
  <ul class="list">
      <li>
          <a href="two.html" data-transition="slide-in">
              Go to page 2
          </a>
          <span class="chevron"></span>
      </li>
  </ul>
</div>

Have a link you don't want to intercepted by push? Try this:

<!-- Use data-ignore="push" to prevent the push.js interception -->
<a href="http://www.google.com" data-ignore="push">Google<a>

Push.js binds an event to the document that returns a detail object and can be used to fire a callback.

// Only needed if you want to fire a callback
window.addEventListener('push', myFunction);

Page setup

3 simple rules for structuring your Ratchet pages

  1. 1. Fixed bars come first

    All fixed bars (.bar-title, .bar-tab, .bar-header-secondary, .bar-footer) should always be the first thing in the <body> of the page. This is really important!

  2. 2. Everything else goes in .content

    Anything that's not a .bar-title or .bar-tab should be put in a div with the class "content". Put this div after the bars in the <body> tag. The .content div is what actually scrolls in a Ratchet prototype.

  3. 3. Don't forget your meta tags

    They're included in the template.html page included in the download, but make sure they stay in the page. They are important to Ratchet working just right.