Design Haven What's New?

How To Build A Ruby Gem With Bundler, Test-Driven Development, Travis CI And Coveralls, Oh My! 0

How To Build A Ruby Gem With Bundler, Test-Driven Development, Travis CI And Coveralls, Oh My!

Ruby is a great language. It was designed to foster happiness and productivity in developers, all the while providing tools that are effective and yet focused on simplicity. One of the tools available to the Rubyist is the RubyGems package manager. It enables us both to include “gems” (i.e. packaged code) that we can reuse in our own applications and to package our own code as a gem to share with the Ruby community. We’ll be focusing on the latter in this article.

I’ve written an open-source gem named Sinderella (available on GitHub), and in this article I’ll go through all of the steps I took to write the code (including the test-driven development process) and how I prepared it for release as a gem via RubyGems. I’ll also show you how to set up your tests to run through a continuous integration (CI) server using the popular Travis CI service.

In case you’re unfamiliar with CI, it refers to the process of merging code with a central repository, with the aim of preventing integration problems down the road in a project’s life cycle. (If you use a version control system such as git and a decentralized code repository such as GitHub, then you might already be familiar with these concepts.)

Finally, I’ll show you how to use Coveralls to measure the code coverage of your tests and to obtain a statistical history of your commits.

Image credit: The Ruby and Bundler logos, along with the Travis CI mascot.

What We’ll Cover

What Does Sinderella Do?

As described in the README on GitHub, Sinderella allows the author to “pass a code block to transform a data object for a specific period of time.” So, if we provide data like the following…

{ :key => 'value' }

… then we could, for example, convert it to the following for a set period of time:

{ :key => 'VALUE' }

Once the time period has expired, the data is returned to its normal state.

Sinderella is made up of two files: the main application and a data store that holds the original and transformed data.

Later in this article, I’ll describe my development process for creating the gem, and we’ll review some of the techniques required to produce a robust and stable gem.

What We Won’t Cover

To be clear, this article is focused on creating a Ruby gem using Bundler and on following best practices, such as test-driven development and CI.

We won’t cover how to write Ruby code or how we developed the Sinderella gem. Nor will we cover how to write RSpec tests (although we will demonstrate how to set up RSpec). RSpec is a detail of implementation and can be swapped out for any testing library that you deem appropriate.

Additional Requirements

To get started, you’ll need to register for accounts with the following services:

Registering for these services is free. Travis CI is free for all open-source projects (which this will be). You may pay for a Pro account, which allows you to set up CI for your private code repositories, but that’s not needed for what we’ll be doing here.

You’ll also need to be comfortable working in the command line. You don’t have to be a Unix shell scripting wizard, but I’ll be working here exclusively in a shell environment (specifically, using the Terminal on Mac OS X) to do everything, including running shell commands, opening multiplexers (such as tmux) and editing code (with Vim).

Which Version Of Ruby To Use

Ruby has many different flavors:

  • Ruby (also known as Matz’s Ruby Interpreter) is the original language, written in C.
  • Rubinius is an implementation of Ruby that is written mainly with Ruby.
  • JRuby is an implementation of Ruby built on top of the Java Virtual Machine (JVM), with Java.

I deliberately used JRuby to implement Sinderella because part of the gem’s code relies on “threads,” and MRI doesn’t provide true threading.

JRuby provides a native thread implementation because it is built on top of the JVM. But really, using any of the above variations would have been fine.

Unfortunately, though, it’s not all clear sailing with JRuby. Quite a few gems still use C extensions (i.e. code written in C that Ruby can import). At the moment, you can enable a flag in JRuby that allows it to use C extensions, but doing so is merely a temporary solution because this option is expected to be removed from JRuby in future releases.

This could be an issue, for example, if you’re using Pry (a replacement for Ruby’s irb REPL). Pry works fine with JRuby, but you wouldn’t be able to take advantage of the equally amazing pry-plus extension, which offers many extra debugging capabilities, because some of its dependencies rely on C extensions.

I’ve worked around this limitation somewhat by using pry-nav. It’s not as good and can be a little buggy in places when used under JRuby, but it gets the job done.


To help us create the gem, we’ll use the popular Bundler gem.

Bundler is primarily designed to help you manage a project’s dependencies. If you’ve not used it before, then don’t worry because we’ll be taking advantage of a lesser known feature anyway, which is its ability to generate a gem boilerplate. (It also provides some other tools that will help us manage our gem’s packaging, which I’ll get into in more detail later on.)

Let’s begin by installing Bundler:

gem install bundler

Once Bundler is installed, we can use it to create our gem. But before doing that, let’s review some other dependencies that we’ll need.


Developing the Sinderella gem requires five dependencies. Four are needed during the development process and won’t be needed in production. The fifth is a “hard” dependency, meaning that it is needed for the Sinderella gem to function properly.

Of these dependencies, Crimp and RSpec are specific to Sinderella. So, when developing your own gem, you would likely replace them with other gems.


We need to install RubyGems in order to take advantage of the package manager and its built-in gem commands (which Bundler will wrap with its own enhancements).


RSpec is a testing framework for the Ruby programming language. We’ll cover this in more detail later on in the article.

When building your own gem, you might want to swap RSpec for a different testing tool. Another popular option is Cucumber.


Guard is a command-line tool that responds to events. We’ll be using it to more easily write code for test-driven development. It works by monitoring files that you tell it to watch and then, when it notices changes to those files, triggering some command that you specify based on the type of file that was changed.

This comes in really handy when you’re running tests in a multiplexer such as tmux or when using a terminal such as iTerm2 (which supports multiple terminal windows being open at once), because while you’re editing the code in one terminal, you can get instant feedback to breaking tests as you work on the code. This is known as a tight feedback loop (more on this later).


Pry is a replacement REPL for Ruby’s standard irb. It offers everything the standard irb does but with a lot of additional features. It’s useful for testing code to see how it works and whether the Ruby interpreter fails to run it. It’s also useful for debugging code when something doesn’t work the way you expect.

It didn’t have much of a presence in the development of Sinderella, but it is such an important tool that I felt it deserved more than a cursory mention. For example, if you’re unsure of how a particular Ruby feature works, you could test drive it in Pry.

If you want to learn more about how to use it, then watch the screencast on Pry’s home page.


Crimp is a gem released by the BBC that allows you to convert a piece of data into a MD5 hash.

Generating A Boilerplate

OK, now we’ve finally gotten to the point where we can generate the set-up files that will configure our gem file.

As mentioned, Bundler has the tools to generate the foundation of a gem so that we don’t have to type it all out by hand.

Now, open up the terminal and run the following command:

bundle gem sinderella

When that command is run, the following is generated:

❯ bundle gem sinderella
  create  sinderella/Gemfile
  create  sinderella/Rakefile
  create  sinderella/LICENSE.txt
  create  sinderella/
  create  sinderella/.gitignore
  create  sinderella/sinderella.gemspec
  create  sinderella/lib/sinderella.rb
  create  sinderella/lib/sinderella/version.rb
Initializing git repo in /path/to/Sinderella

Let’s take a moment to review what we have.

Folder Structure

Bundler has automatically created a lib directory for us, which holds a single Ruby file named after our project. The name of the directory is extracted from the name provided via the bundle gem command.

Be aware that if you specify a hyphen (-) in the gem’s name, then Bundler will create a deeper folder structure by using the hyphen as a delimiter. For example, if your command looks like bundle gem foo-bar, then the following directory structure would be created:

├── lib
│   └── foo
│       ├── bar
│       │   ├── bar.rb
│       │   └── version.rb
│       └── bar.rb

This is actually quite useful when you’re producing multiple gems that are all namespaced under a single project. For a real-world example of this, look at BBC News’ GitHub repository, which has multiple open-source gems published under the namespace alephant.


The gemspec file is used to define the particular configuration of your gem. If you weren’t using Bundler, then you would need to manually create this file (according to RubyGems’ documentation).

Below is what Bundler generates for us:

# coding: utf-8
lib = File.expand_path('../lib', __FILE__)
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
require 'sinderella/version' do |spec|          = "sinderella"
  spec.version       = Sinderella::VERSION
  spec.authors       = ["Integralist"]         = [""]
  spec.summary       = %q{TODO: Write a short summary. Required.}
  spec.description   = %q{TODO: Write a longer description. Optional.}
  spec.homepage      = ""
  spec.license       = "MIT"

  spec.files         = `git ls-files -z`.split("\x0")
  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
  spec.require_paths = ["lib"]

  spec.add_development_dependency "bundler", "~> 1.5"
  spec.add_development_dependency "rake"

As you’ll see later, this is a basic outline of the final gemspec file that we’ll need to create. We’ll end up adding to this file some of the other dependencies that our gem will need to run (both development and production dependencies).

For now, note the following details:

  • $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
    This adds the lib directory to Ruby’s load path, which makes require’ing files elsewhere in the code a little cleaner.
  • require 'sinderella/version'
    This loads in a version.rb file, which was generated when Bundler constructed our boilerplate. This file serves as a way to implement semantic versioning in our gem releases. Every time we release the gem, we’ll need to update the version number; then, when we run the particular Bundler command to release the gem, it will automatically pull in the updated value to our gemspec file.
  • do |spec|
    Here, we define a new specification and include properties such as the name of the gem, the version number (see the previous point), a list of the authors of the gem and a contact email address. We can also include some descriptive text about the gem.
  • Next, we define the files to include in the gem. Any executable files found are injected dynamically into the file by looping through a bin directory (if one is found). We also dynamically inject a list of test files (which we’ll see later on when we create a spec folder to hold the tests that will ensure that the gem works as expected).
  • Finally, we define the dependencies, including both runtime and development dependencies. At the moment, there is only the latter, but soon enough we’ll have one runtime dependency to add.

The RubyGems guides has full details on the specification. You could configure a whole host of settings, but Bundler helps us by defining the essential ones.


In a typical Ruby project, you’ll find that the Gemfile is filled with a list of dependencies, which Bundler then collates and installs for you. In this instance, because we’re generating a gem and not writing a standard application, our Gemfile will actually be pretty bare, made up of two lines: one to tell Bundler where to source the gems from, and the other to inform Bundler that the dependencies are listed in the gemspec file instead.


Again, in a typical Ruby application, a Rakefile will contain many different tasks (written in Ruby) that you can execute via the command line. In this case, a one-line Rakefile has been provided that loads bundler/gem_tasks. That in turn loads additional rake commands that Bundler adds to make it easier to build and deploy your gem. We’ll see how to use these commands later.


Because we’re releasing code that could potentially be used by other developers, Bundler generates an MIT licence by default and dynamically injects the current year and your user name into it.

Feel free to either delete it or replace it with another license if the MIT one doesn’t fit your needs, although it’s pretty standard and relevant to most projects.


Lastly, Bundler has taken the tediousness out of generating a README file. It includes TODO messages wherever relevant, so that you know what needs to be manually added before the gem can be built (such as a description of the gem and a code example that shows how you expect the gem to be used). It also automatically generates installation instructions and a section on how other developers can fork your code and contribute new features and bug fixes.

One other benefit of Bundler is that it delivers a consistent code base across all gems you create. All gems will have the same structure, and the consistency across content such as the README file will make it easier for users who integrate more than one of your gems to understand them.

Test-Driven Development

Test-driven development (TDD) is the process of building code on top of supporting tests. Sinderella was developed using its principles.

The guiding steps are “red, green, refactor,” and TDD fundamentally breaks down as the following:

  1. Write a test.
  2. Run the test and watch it fail (because there is no code yet for it to pass).
  3. Write the least amount of code to pass the test (literally, hack it together).
  4. Refactor the code so that it’s cleaner and better written.
  5. If the test has failed through refactoring, then start the red, green, refactoring process again.

This is sometimes referred to as a tight feedback loop: getting quick or instant feedback on whether code is working.

By writing the tests first, you ensure that every line of code exists for a reason. This is an incredibly powerful principle and one you should recall when caught in a debate over whether TDD “sucks” or “takes too long.”

Starting a project with tests can feel daunting. But in addition to ensuring that every line of code exists for a reason, it provides an opportunity for you to properly design the APIs.


As for writing tests for Sinderella, I chose to use RSpec, which is described thus on its website:

RSpec is a testing tool for the Ruby programming language. Born under the banner of behaviour-driven development, it is designed to make test-driven development a productive and enjoyable experience

In order to use RSpec in our gem, we’ll need to update the gemspec file to include more dependencies:

spec.add_development_dependency "rspec"
spec.add_development_dependency "rspec-nc"
spec.add_development_dependency "guard"
spec.add_development_dependency "guard-rspec"
spec.add_development_dependency "pry"
spec.add_development_dependency "pry-remote"
spec.add_development_dependency "pry-nav"

As you can see, we’ve added RSpec to our list of dependencies, but we’ve also included rspec-nc, which provides native notifications on Mac OS X (rspec-nc is a nicety and not essential to produce the gem). Having notifications at the operating-system level can be quite handy, allowing you to do other things (perhaps check email) while tests run in the background.

We’ve also added (as you would expect) guard as a dependency, as well as guard-rspec, which Guard will need in order to understand how to handle RSpec-specific requests. This suite of Pry tools will debug any problems we come across and will be useful for any gems you develop in future.

RSpec Rake Tasks

Now that we’ve updated gemspec to include RSpec as a dependency, we’ll need to add an RSpec-related Rake task to our Rakefile, which will enable us (manually) or Guard to execute the task and run the RSpec test suite:

require 'rspec/core/rake_task'
require 'bundler/gem_tasks'

# Default directory to look in is `/specs`
# Run with `rake spec` do |task|
  task.rspec_opts = ['--color', '--format', 'nested']

task :default => :spec

In the updated version of Rakefile above, we are loading an additional file that is packaged with RSpec (require 'rspec/core/rake_task'). This new file adds some RSpec-related modules and classes for us to use.

Once this code has loaded, we create a new instance of the RakeTask class (created when we loaded rspec/core/rake_task) and pass it a code block to execute. The code block we pass will define the options for our RSpec test suite.

Spec Files

Now that the majority of the RSpec test suite configuration is in place, the last thing we need to do is add a test file.

Let’s create a spec directory and, inside that, create sinderella_spec.rb:

require 'spec_helper'

describe Sinderella do
  it 'does stuff' do
    pending # no code yet

You’ll see that we’ve included a temporary specification that states that the code “does stuff.” When the test suite is run, then this test will not cause any errors, even though no code has been implemented yet, because we have marked the test as “pending” (an RSpec-specific command). At this point, we’re only interested in getting a barebones set-up in place; we’ll flesh out the tests soon enough.

You may have noticed that we’re also loading another file, named spec_helper.rb. This type of file is typical in an RSpec suite and is used to load any dependencies or libraries that are required for the tests to run. The content of the spec helper file will look like this:

require 'pry'
require 'Sinderella'

All we’ve done here is load Pry (in case we need it for debugging) and the main Sinderella gem code (because this is what we want to test).

Guard And tmux

At this point, we’ve gone over the set-up and preparation of RSpec and Rake (to get our testing framework in place). We also know what Guard is and how it helps us to test the code. Now, let’s go ahead and add a Guardfile to the root directory, with the following contents:

guard 'rspec' do
  # watch /lib/ files
  watch(%r{^lib/(.+)\.rb$}) do |m|

  # watch /spec/ files
  watch(%r{^spec/(.+)\.rb$}) do |m|

This file tells Guard that we’re using RSpec to run our tests. It also defines which directories to watch for changes and what to do when it notices changes. In this case, we’re using regular expressions to match any files in the lib or spec directory and to execute the relevant RSpec command that runs our tests (or to run one specific test).

We’ll see in a minute how to actually run Guard. For now, let’s see how tmux fits this workflow.


Some developers prefer to have separate applications open (for example, a code editor such as Sublime Text and a terminal application to run tests). I prefer to use tmux to have multiple terminal shells open on one screen and to have Vim open on another screen to edit code. Thus, I can edit code and get visual feedback from the terminal about the state of the tests all on one screen. You don’t need to follow the exact same approach. As mentioned, there are other ways to get feedback, but I have found tmux and Vim to be the most suitable.

So, we have two tmux panes open, one in which Vim is running, and the other in which a terminal runs the command bundle exec guard (this is how we actually run Guard).

That command will return something like the following back to the terminal:

❯ bundle exec guard
09:53:55 - INFO - Guard is using Tmux to send notifications.
09:53:55 - INFO - Guard is using TerminalTitle to send notifications.
09:53:55 - INFO - Guard::RSpec is running
09:53:55 - INFO - Guard is now watching at '/path/to/Sinderella' 

From: /path/to/Sinderella/sinderella.gemspec @ line 1 :

 => 1: # coding: utf-8
    2: lib = File.expand_path('../lib', __FILE__)
    3: $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
    4: require 'sinderella/version'
    6: do |spec|

From this point on, you can press the Return key to run all tests at once, which will display the following message in the terminal:

09:57:41 - INFO - Run all
09:57:41 - INFO - Running all specs

This will be followed by the number of passed and failed tests and any errors that have occurred.

Continuous Integration With Travis CI

As mentioned at the beginning, continuous integration (CI) is the process of merging code with a central repository in order to prevent integration problems down the road in a project’s life cycle.

We’ll use the free Travis CI service (which you should have signed up for by now).

Upon first viewing your “Accounts” page in Travis CI, you’ll be presented with a complete list of all of your public GitHub repositories, from which you can select ones for Travis CI to monitor. Then, any time you push a commit to GitHub, Travis CI will run your tests.

Once you have selected repositories, you’ll be redirected to a GitHub “hooks” page, where you can confirm and authorize the configuration.

The Travis CI page for the Sinderella gem is where you can view the entire build history, including both passed and failed tests.


To complete the configuration, we need to add a .travis.yml file. If you’ve enabled your repository from your Travis CI account and you don’t have a .travis.yml file, then Travis CI will throw an error and complain that you need one. Let’s look at the one we’ve set up for Sinderella:

language: ruby
cache: bundler

  - jruby
  - 2.0.0

script: 'bundle exec rake'

    on_failure: change
    on_success: never

Let’s go through each property to understand what it does:

  • language: ruby
    Here, we’re telling Travis CI that the language in which we’re writing tests is Ruby.
  • cache: bundler
    This tells Travis CI that we want it to cache the gems we’ve specified. (Running Bundler can be a slow process, and if your gems are unlikely to change often, then you don’t want to keep running bundle install every time you push a commit, because we want our tests to run as quickly as possible.)
  • rvm:
    This specifies the different Ruby versions and engines that we want our tests to run against (in this case, JRuby and MRI 2.0.0).
  • script: 'bundle exec rake'
    This gives Travis CI the command it requires to run the tests.
  • notifications:
    This indicates how we want Travis CI to notify us. Here, we’re specifying an email address to receive the notifications. We’re also specifying that an email should be sent only if a failure has occurred (there’s no point in getting thousands of emails telling us that nothing is wrong).

Preventing a Test Run

If you’re committing a change that doesn’t affect your code or tests, then you don’t want to waste time watching those non-breaking changes trigger a test run on Travis CI (no matter how fasts the tests are).

The easiest way to avoid this is to add [ci skip] anywhere in your commit message. Travis CI will see this and then happily ignore the commit.

Code Coverage And Statistics With

One last service we’ll use is Coveralls, which you should have already registered for.

Coveralls works with your continuous integration server to give you test coverage history and statistics. Free for open source, pro accounts for private repos.

When you log into Coveralls for the first time, it will ask you to select repositories to monitor. It works like Travis CI, listing all of your repositories for you to enable and disable access. (You can also click a button to resynchronize the repository list, in case you’ve added a repository since last syncing).

To set up Coveralls, we need to add a file that tells Coverall what to do. For our project, we need to add a file to the root directory named .coveralls.yml, in which we’ll include a single line of configuration:

service_name: travis-ci

This tells Coveralls that we’re using Travis CI as our CI server. (If you’ve signed up for a Pro account, then use travis-pro instead.)

We also need to add the Coveralls gem to our gemspec:

spec.add_development_dependency "coveralls"

Finally, we need to include Coveralls’ code in our spec_helper.rb file:

require 'coveralls'

require 'pry'
require 'sinderella'

Notice that we have to load the code before the Sinderella code. If you load Coveralls after the application’s code has loaded, then it wouldn’t be able to hook into the application properly.

Let’s return to our TDD process.

Skeleton Specification

When following TDD, I prefer to create a skeleton of a test suite, so that I have some idea of the type of API to develop. Let’s change the contents of the sinderella_spec.rb file to have a few empty tests:

require 'spec_helper'

describe Sinderella do
  let(:data) {{ :key => 'value' }}
  let(:till_midnight) { 0 }

  describe '.transforms(data, till_midnight)' do
    it 'returns a hash of the passed data' do

    it 'stores original and transformed data' do

    it 'restores the data to its original state after set time' do

  describe '.get(id)' do
    context 'before midnight (before time expired)' do
      it 'returns transformed data' do

    context 'past midnight (after time expired)' do
      it 'returns original data' do

  describe '.midnight(id)' do
    it 'restores the data to its original state' do

Notice the pending command, which is provided by RSpec and allows the tests to run without throwing an error. (The suite will highlight pending tests that still need to be implemented so that you don’t forget about them.)

You could also use the fail command, but pending is recommended for unimplemented tests, particularly before you’ve written the code to execute them. Relish demonstrates some examples.

From here on, I follow the full TDD process and write the code from the outside in: red, green, refactor.

For the first test I wrote for Sinderella, I realized that my code needs a way to create an MD5 hash from a data object, and that’s when I reached for the BBC News’ gem, Crimp. Thus, I had to update the gemspec file to include a new runtime dependency: spec.add_runtime_dependency "crimp".

I won’t go step by step into how I TDD’ed the code because it isn’t relevant to this article. We’re focusing more on the principles of creating a gem, not on details of implementation. But you can get all of the gruesome details from the public list of commits in Sinderella’s GitHub repository.

Also, you might not even be interested in the RSpec testing framework and might be planning on using a different framework to write your gem. That’s fine. Anyway, what follows is the full Sinderella specification file (as of February 2014):


require 'spec_helper'

describe Sinderella do
  let(:data) {{ :key => 'value' }}
  let(:till_midnight) { 0 }

  def create_new_instance
    @id = subject.transforms(data, till_midnight) do |data|
      data.each do |key, value|
        data.tap { |d| d[key].upcase! }

  describe '.transforms(data, till_midnight)' do
    it 'returns a MD5 hash of the provided data' do
      expect(@id).to be_a String
      expect(@id).to eq '24e73d3a4f027ff81ed4f32c8a9b8713'

  describe '.get(id)' do
    context 'before midnight (before time expired)' do
      it 'returns the transformed data' do
        expect(subject.get(@id)).to eq({ :key => 'VALUE' })

    context 'past midnight (after time expired)' do
      it 'returns the original data' do
        Sinderella.reset_data_at @id
        expect(subject.get(@id)).to eq({ :key => 'value' })

  describe '.midnight(id)' do
    context 'before midnight (before time expired)' do
      it 'restores the data to its original state' do
        expect(subject.get(@id)).to eq({ :key => 'value' })


require 'spec_helper'

describe DataStore do
  let(:instance)    { DataStore.instance }
  let(:original)    { 'bar' }
  let(:transformed) { 'BAR' }

  before(:each) do
      :id => 'foo',
      :original => original,
      :transformed => transformed

  describe 'set(data)' do
    it 'stores original and transformed data' do
      expect(instance.get('foo')[:original]).to eq(original)
      expect(instance.get('foo')[:transformed]).to eq(transformed)

  describe 'get(id)' do
    it 'returns data object' do
      expect(instance.get('foo')).to be_a Hash
      expect(instance.get('foo').key?(:original)).to be true
      expect(instance.get('foo').key?(:transformed)).to be true

  describe 'reset(id)' do
    it 'replaces the transformed data with original data' do
      foo = instance.get('foo')
      expect(foo[:original]).to eq(foo[:transformed])

Passing Specification

Here is the output of our passed test suite:

❯ rake spec
/path/to/.rubies/jruby-1.7.9/bin/jruby -S rspec ./spec/data_store_spec.rb ./spec/sinderella_spec.rb --color --format nested

    stores original and transformed data
    returns data object
    replaces the transformed data with original data

  .transforms(data, till_midnight)
    returns a MD5 hash of the provided data
    before midnight (before time expired)
      returns the transformed data
    past midnight (after time expired)
      returns the original data
    before midnight (before time expired)
      restores the data to its original state

Finished in 0.053 seconds
7 examples, 0 failures

Design Patterns

According to Wikipedia:

A design pattern in architecture and computer science is a formal way of documenting a solution to a design problem in a particular field of expertise.

Many design patterns exist, one of which in particular is usually frowned on, the Singleton pattern.

I won’t debate the merits or problems of the Singleton design pattern, but I opted to use it in Sinderella to implement the DataStore class (which is the object that stores the original and transformed data), because what would be the point of having multiple instances of DataStore if the data is expected to be shared from a single access point?

Luckily, Ruby makes it really easy to create a Singleton. Just add include Singleton in your class definition.

Once you’ve done that, you will be able to access a single instance of your class only via an instance property — for example, MyClass.instance.some_method().

We saw the specification (or test file) for DataStore in the previous section. Below is the full implementation of DataStore:

require 'singleton'

class DataStore
  include Singleton

  def set(data)
    hash_data = {
      :original    => data[:original],
      :transformed => data[:transformed]
    }[:id], hash_data)

  def get(id)

  def reset(id)
    original  = container.fetch(id)[:original]
    hash_data = {
      :original => original,
      :transformed => original
    }, hash_data)


  def container
    @store ||=


You might have seen some nice green badges in your favorite GitHub repository, indicating whether the tests associated with the code passed or not. Adding these to the README is straightforward enough:

[![Build Status](]( 

[![Gem Version](](

[![Coverage Status](](

The first badge is provided by Travis CI, which you can read more about in the documentation.

The second is provided by RubyGems. You’ll notice on your gem’s page a “badge” link, which provides the required code and format (in this case, in Markdown format).

The third is provided by Coveralls. When you visit your repository page in the Coveralls application, you’ll see a link to “Get badge URLS”; from there, you can select the relevant format.

REPL-Driven Development

Tests and TDD are a critical part of the development process but won’t eliminate all bugs by themselves. This is where a tool such as Pry can help you to figure out how a piece of code works and the path that the code takes during a conditioned execution.

To use Pry, enter the pry command in the terminal. As long as Pry is installed and available from that directory, you’ll be dropped into a Pry session. To view all available commands, run the help command.

Testing a Local Gem Build

If you want to run the gem outside of the test suite, then you’ll want to use Pry. To do this, we’ll need to build the gem locally and then install that local build.

To build the gem, run the following command from your gem’s root directory: gem build sinderella.gemspec. This will generate a physical .gem file.

Once the gem is built and a .gem file has been created, you can install it from the local file with the following command: gem install ./sinderella-0.0.1.gem.

Notice that the built gem file includes the version number, so that you know you’re installing the right one (in case you’ve built multiple versions of the gem).

After installing the local version of the gem, you can open a Pry session and load the gem with require 'sinderella' and continue to execute your own Ruby code within Pry to test the gem as needed.

Releasing Your Gem

Once our gem has passed all of our tests and we’ve built and run it locally, we can look to release the gem to the Ruby community by pushing it to the RubyGems server.

To release our gem, we’ll use the Rake commands provided by Bundler. To view what commands are available, run rake --task. You’ll see something similar to the following output:

rake build    # Build sinderella-0.0.1.gem into the pkg directory
rake install  # Build and install sinderella-0.0.1.gem into system gems
rake release  # Create tag v0.0.1 and build and push sinderella-0.0.1.gem t...
rake spec     # Run RSpec code examples
  • rake build
    This first task does something similar to gem build sinderella.gemspec but placing the gem in a pkg (package) directory.
  • rake install
    The second task does the same as gem install ./sinderella-0.0.1.gem but saves us the extra typing.
  • rake release
    The third task is what we’re most interested at this point. It creates a tag in git, indicating the relevant version number, pulled from the version.rb file that Bundler created for us. It then builds the gem and pushes it to RubyGems.
  • rake spec
    The fourth task runs the tests using the test runner (in this case, RSpec), as defined and configured in the main Rakefile.

To release our gem, we’ll first need to make sure that the version number in the version.rb file is correct. If it is, then we’ll commit those changes and run the rake release task, which should give the following output:

❯ rake release
sinderella 0.0.1 built to pkg/sinderella-0.0.1.gem.
Tagged v0.0.1.
Pushed git commits and tags.
Pushed sinderella 0.0.1 to

Now we can view the details of the gem at, and other users may access our gem in their own code simply by including require 'sinderella'.


Thanks to the use of Bundler, the process of creating a gem boilerplate is made a lot simpler. And thanks to the principles of TDD and REPL-driven development, we know that we have a well-tested piece of code that can be reliably shared with the Ruby community.

(al, il)

© Mark McDonnell for Smashing Magazine, 2014.

How To Build A Ruby Gem With Bundler, Test-Driven Development, Travis CI And Coveralls, Oh My! 0

How To Build A Ruby Gem With Bundler, Test-Driven Development, Travis CI And Coveralls, Oh My!

Ruby is a great language. It was designed to foster happiness and productivity in developers, all the while providing tools that are effective and yet focused on simplicity.

How To Build A Ruby Gem With Bundler, Test-Driven Development, Travis CI And Coveralls, Oh My!

One of the tools available to the Rubyist is the RubyGems package manager. It enables us both to include “gems” (i.e. packaged code) that we can reuse in our own applications and to package our own code as a gem to share with the Ruby community. We’ll be focusing on the latter in this article.

The post How To Build A Ruby Gem With Bundler, Test-Driven Development, Travis CI And Coveralls, Oh My! appeared first on Smashing Magazine.

Involving Clients In Your Mobile Workflow 0

Involving Clients In Your Mobile Workflow

A lot of mobile-minded talented folks across the globe produce great work, but yet sometimes you still hear many of them complain about their relationships with their clients. They often mention feeling isolated and not truly understanding what the client really needed.

This lack of personal interaction often leads to misunderstanding, as well as less awareness of and appreciation for all your hard work. While involving clients in your mobile workflow can be challenging, really working together will make a big difference. In this article, I’ll share some important things I’ve learned about involving clients in my mobile workflow. Let’s dive into some tips and tricks that I use every day.

Work Out Your Manifesto

Projects don’t happen overnight. It usually takes a few meetings to get to know the client and to discuss collaboration. Your company’s business strategists and account managers invest a lot of time and energy in this process. While they will often seem to distance themselves from your daily work, speaking with them is a real window of opportunity. These “suits” are the first ones to meet potential clients, and they convey your company’s vision, portfolio and creative approach. They can be a great help in nurturing a more involved relationship.

A great way to approach this internal conversation is to work out a manifesto, a summary of your creative vision and beliefs. Get together with your team and discuss your existing workflow and how it could further support what you really stand for as a team. Ask the team lead to help you work it out and make the message tangible. Do this simply by making a presentation to your colleagues. But why stop there? You could design posters, flyers, even stickers for your team so that they can help you spread the word.

Design is not an afterthought,” from Little Miss Robot’s manifesto.
“Design is not an afterthought,” from Little Miss Robot’s manifesto. (Large version)

We were getting really frustrated with clients asking us to define or optimize their mobile experience, when in fact they just wanted us to make things “prettier.” The slide above helps our client service directors to detect how potential clients really think about design. If we see that they don’t value our vision or approach, then we respectfully decline to work with them. Involvement starts with finding clients who want you to work with them, instead of for them.

Don’t Miss The Kick-Off

A kick-off meeting is the perfect opportunity to raise awareness of and appreciation for your mobile workflow. Learn as much as possible about the client, and find out how they would like you to help their business. Do this simply by asking about their vision, strategy and goals. Also great is to ask what inspires them and to get insight into their competitive research and analysis. From the minute you show true interest in their business, you are changing the way they look at you. By immediately working with them, you become their partner, instead of just someone who designs and codes.

A kick-off meeting is also a great time to double-check that you are on the same page. Sometimes we forget that our creative jargon might confuse clients. Big Spaceship points this out in its inspiring manual (PDF):

“We act like humans, we talk like humans, and we think like humans. And we call out anyone who does the opposite.”

In the last two years, I’ve learned that clients find it very hip to focus on responsive design, even if they don’t clearly understand it. Too often, it leads to a discussion on size and dimensions, when the conversation should be conceptual and strategic. Reserve some time in your kick-off meeting to explain what “responsive” means and why you believe in its value. Educate the client and steer the conversation towards what is really needed to make the project better. And if you notice that a certain topic needs more time and attention, host a mini-workshop to talk it through.

Dealing With Isolation

I don’t understand why some account and project managers try to keep their team away from the client as much as possible. Granted, it makes perfect sense that they manage the client, oversee the scope, deadlines and budget, and handle the communication and next steps. But when the work is in progress, keeping the team isolated doesn’t add any value. If this happens to you, explain to the manager that getting direct feedback from the client will help you fine-tune the product better and more quickly — a win-win for everyone.

At Little Miss Robot, we try to hold half of our meetings in our studio. Clients find it inspiring to be in this creative environment — especially because it is where their own product is being developed. In long-term projects, we also ask the client to designate a space at their office for our team to work on the project. When developing Radio+, we worked at the client’s headquarters twice a week. Anyone could hop in and out of the space and have informal conversations about the work. Not only did it create a great atmosphere, but we also received the most valuable feedback during these times. Highly recommended!

0The Radio+ room, a shared workspace.
The Radio+ room, a shared workspace. (Large version)

Seeing Things

A typical project starts by the team exploring or defining what they will create. A lot of teams rely on textual aids, such as functional requirements. While these documents contain a lot of detail, I always end up having to address misinterpretations. The worst part is that these “minor” misunderstandings always pop up during the production stage, resulting in increased time and expenses. Have you noticed on these occasions that the client says they “saw” things a bit differently? This is why I recommend using text documents to scope features and using visual resources to describe them. Mind maps, wireframes, storyboards and paper prototypes are my personal favorites.

The wireframe for the Radio+ mobile website.
The wireframe for the Radio+ mobile website. (Large version)

I always encourage clients to get involved in generating these visual resources. Having them by your side during a brainstorm or a UX workshop is really helpful. While they wouldn’t consider themselves designers, I’m always challenged and inspired by their thinking and how they see things.

Feeling The Progress

Throughout the mobile development process, you will probably invite the client to several meetings to discuss the status of the project and to demo the product. Make sure you have something tangible to talk about. If a meeting is just about process, time or budget, then let the project manager handle it. Build momentum when meeting in person, and show your work in progress on real devices! Of course, you could print out the design or demo the application on a big screen, but the client should be able to feel the progress in their hands, too. Feeling a product grow in your hands is a much more powerful and engaging experience!

Some great tools exist to share designs across devices. We use AppTaster to share mockups, Dropbox to share designs and TestFlight to distribute apps to clients. If we are building a mobile website, then we just host it on the client’s servers internally, which allows them to view the latest version whenever they want.

Over-the-air beta testing for TestFlight.
Over-the-air beta testing for TestFlight. (Large version)

Happy Ending

Involving clients in your mobile workflow is the key to better understanding their problems, goals and strategies. You’ll also raise more awareness of and appreciation for your work, thus reducing negative energy and making discussions more positive and constructive. However big or small your team or client, it all starts with a desire to be involved. These take-aways can help you with that:

  1. Create a manifesto that explains what your team stands for.
  2. Hold a kick-off meeting to ask the client about their vision, strategy and goals.
  3. Use both your and their offices to meet.
  4. Scope features in text documents, and describe them in visual documents.
  5. Take advantage of third-party tools to share your work in progress on real devices.

Last but not least, read Jeremy Girard’s article on how to wrap up a project and follow up afterwards. This is critical to building and maintaining a long-term relationship. Most importantly, it will lead to future business because the client will already know and value your work.

Please feel free to share your experiences and thoughts in the comments below. I’m already looking forward to reading them.

(al, ml)

© Thomas Joos for Smashing Magazine, 2014.

Involving Clients In Your Mobile Workflow 0

Involving Clients In Your Mobile Workflow

A lot of mobile-minded talented folks across the globe produce great work, but yet sometimes you still hear many of them complain about their relationships with their clients. They often mention feeling isolated and not truly understanding what the client really needed.

Involving Clients In Your Mobile Workflow

This lack of personal interaction often leads to misunderstanding, as well as less awareness of and appreciation for all your hard work. While involving clients in your mobile workflow can be challenging, really working together will make a big difference. In this article, I’ll share some important things I’ve learned about involving clients in my mobile workflow. Let’s dive into some tips and tricks that I use every day.

The post Involving Clients In Your Mobile Workflow appeared first on Smashing Magazine.

Interview With Khajag Apelian: “Type Design Is Not Only About Drawing Letters” 0

Interview With Khajag Apelian: “Type Design Is Not Only About Drawing Letters”

Having started his career studying under some of the best typographic minds in the world, Khajag Apelian not only is a talented type and graphic designer, unsurprisingly, but also counts Disney as a client, as well as a number of local and not-for-profit organizations throughout the Middle East.

Even more impressive is Khajag’s willingness to take on work that most people would find too challenging. Designing a quality typeface is a daunting task when it’s only in the Latin alphabet. Khajag goes deeper still, having designed a Latin-Armenian dual-script typeface in four weights, named “Arek”, as well as an Arabic adaptation of Typotheque’s Fedra Display.

Khajag ApelianGiven his experience in working between languages, it’s only logical that Khajag’s studio maajoun was chosen by the well-known and beloved Disney to adapt its logos for films such as Planes and Aladdin into Arabic, keeping the visual feel of the originals intact.

Q: Could you please start by telling us more about some of the typefaces you’ve designed?

Khajag: Well, I’ve only designed one retail font, and that is Arek. It started as my final-year project in the Type and Media program at KABK (Royal Academy of Art, the Hague). Arek was my first original typeface, and it was in Armenian, which is why it is very dear to me. I later developed a Latin counterpart in order to make it available through Rosetta, a multi-script type foundry.

Another font I designed is Nuqat, with René Knip and Jeroen van Erp. Nuqat was part of the “Typographic Matchmaking in the City” project, initiated by the Khatt Foundation between 2008 and 2010. In this project, five teams were commissioned to explore bilingual type for usage in public spaces.

Arek is a dual-script Latin-Armenian typeface family in four weights, with matching cursive styles. (Large preview)

I’ve also worked on developing the Arabic companion of Fedra Display by Typotheque. The font is not released yet but will be soon, hopefully in the coming year, so keep an eye on Typotheque if you’re interested.

Q: How did you start designing type?

Khajag: We had a foundational course in type design at Notre Dame University in Lebanon (NDU) during my bachelor’s degree. Actually, it was more like a project within a course, where we were asked to design an “experimental Arabic typeface” — something that was quite basic and that didn’t really involve type design, which I later realized when I entered the Type and Media program. So, that was the first project I worked on that could be considered close to designing type. The outcome is nothing to be proud of, but the process was a lot of fun.

Then, I started to work more and more with letters, although I never knew I could develop this interest, let alone study it later on. I only found out about the program at KABK during my final year at the university, when NDU graduate Pascal Zoghbi came to the school to present his Type and Media thesis project. That did it for me — two years later, I was there!

Typographic Matchmaking 2.0 parts 1-3. (Watch on YouTube)

Q: Tell us about the course at KABK. Did you focus only on designing Latin typefaces, or were you able to develop your skill in designing Arabic faces, too?

Khajag: The year at KABK was one of the best times I’ve had. It was intense, rich, fun and fast. It’s incredible how much you develop when surrounded by teachers who are considered to be the top of the typographic world and classmates who were selected from different places around the world, each bringing their own knowledge and experience to the table.

During the first semester, we tackled the basics of type design in calligraphy classes, practicing and exercising the principles of Latin type. We mostly learned the fundamentals of contrast, letter structure and spacing. This continued over the year through sketching exercises, designing type for different media and screens, and historical revivals.

Sketching exercises
A couple of type-drawing exercises on TypeCooker. (Image source)

Adapting these principles to the specifics of other scripts, like Arabic and Armenian, had to come from a more personal learning effort. But despite their modest knowledge of these scripts, the instructors are capable of guiding you through your final project. At the time, I decided to go with Armenian for my final project, but others have worked with other scripts, and the results have been strong and impressive.

Q: How do you keep the spirit of a typeface intact when moving from one language to another? Is it easier to maintain this feel when designing the Latin counterpart of an Armenian typeface, as you did with Arek, or when moving from Latin to Arabic, as you’re doing with Fedra Display?

Khajag: I think each project presents its own challenges to translating a certain spirit in different scripts. In the case of Arek, I started designing the Armenian without thinking about designing a Latin counterpart to it. So, my focus was entirely on one script. The process involved a lot of investigation of old Armenian manuscripts, from which my observations and findings were translated into the typeface. This naturally created a very strong spirit that I had to retain when I moved to designing the Latin counterpart.

Armenian and Latin letter proportions and constructions have certain similarities, which helped with the initial drawing of the Latin letters. I later had to reconsider some details, like the x-height, the serifs and the terminals, in order to achieve the ideal visual harmony.

This Arabic adaptation of Fedra Display. (Large preview)

In the case of Fedra Display Arabic, the spirit of the typeface was already there. The challenge was to translate the extreme weights of Fedra Sans Display to the existing Fedra Arabic. The Latin font is designed for headlines and optimized for a compact setting. These were important to retain when designing the Arabic counterpart. I experimented a lot with the weight distribution of the letterforms, something that is an established practice in the Latin script but not in the Arabic.

I had to find the right width and the maximum height of the letterforms in order to achieve similar blackness while maintaining the same optical size. Whereas, for the hairline, it was necessary to keep the compact feature of the Latin without undermining the Arabic script. A set of ligatures was designed to further enhance the narrowness of the font.

Q: Do you design only Arabic typefaces? If so, is there a particular reason for that?

Khajag: Besides Arek and a few other small projects I’ve been involved in, I mostly work with Arabic. The first direct reason is where I live, of course. Most of the time, clients in the region need to communicate in two languages, and that’s usually Arabic and English, or Arabic and French. The other reason is the number of Arabic fonts available compared to Latin fonts. Usually, when looking to communicate in English, I can find a way to do it through existing Latin fonts, but that’s not always the case with Arabic.

Although, I have to admit that a lot of good Arabic type is emerging in the design world nowadays. Still, there aren’t that many Arabic typefaces, and with time the good ones become overused and everyone’s designs start to look similar. This is why I look to differentiate my work through type. I do not always design complete functional typefaces; rather, I often develop “incomplete” fonts that I can use to write a word or a sentence for a poster or a book cover, and different lettering pieces here and there.

The identity poster and catalogue for “Miniatures: A Month for Syria” event, organized by SHAMS. (Large preview)

Q: Do you prefer to design Arabic typefaces that hold true to the calligraphic origins of the script, or is it more interesting to depart from those origins somewhat, as you did with Nuqat?

Khajag: I think Nuqat is quite an extreme case of departing from calligraphy. I consider it an experiment rather than a functional typeface. In any case, I don’t think I have a particular preference for typefaces to design. I am very much intrigued by the process, and in both cases there are some quite interesting challenges to tackle. A big responsibility comes with designing a typeface that must remain true to its calligraphic origins, something that comes with a lot of history and that has reached a level of perfection. And when you depart from that, you go through an abstraction process that can also be a fun exercise.

Nuqat is a display typeface designed by Khajag Apelian and René Knip for the “Typographic Matchmaking in the City” project, initiated by the Khatt Foundation. (Large preview)

Q: Where does your love of typography and graphic design come from?

Khajag: Like most teenagers about to start university, I was confused about my subject of study. At the time, I was part of a dance troupe with a friend who used to be a graphic designer. I liked her quite a bit and thought I could enroll in graphic design to be “cool” like her! I didn’t know what graphic design was about at the time. And so I enrolled. The foundation year was all about color theory, shapes and composition. It wasn’t until the second year or so that I started to realize what design was really about. Luckily, I loved it.

Later on, I took courses with Yara Khoury, and thanks to her I really got to appreciate typography. Yara was heavily influenced by different European schools that put typography on a pedestal, and she managed to transfer that to me and to other students. At NDU, we were exposed to the work of various designers from the Bauhaus and Swiss schools, and we were trained to capture the details and understand the function of type within graphic design. I was particularly fascinated by how one can go all the way from designing something that goes unnoticed by the reader to something that is very present and expressive, all just with type.

Q: Did you enjoy the visual departure from the Arabic culture you were surrounded by and brought up in, into the Modernist European one you were learning about? Did you ever find the aesthetic difference between the two difficult to navigate?

Khajag: Very much, actually. It wasn’t difficult to navigate per se, but rather overwhelming, maybe? Everything in the Netherlands is designed, and many of those things are featured in books as exemplary design. I had always been exposed to this through books and the Internet, but actually being immersed in it was another experience. One funny incident was when I spotted a police car for the first time, knowing it was branded by Studio Dumbar. I was so excited, I almost wanted to take a picture with them.

Q: How did you start off in the design industry? Could you also describe your role at your current company?

Khajag: My first job as a designer was in branding with Landor Associates in Dubai. I worked there for around a year, before going to the Netherlands for my master’s. After graduation, I extended my visa for a year and worked freelance with several Dutch design studios on projects that involved designing with Arabic. My work partner, Lara, was also living and working in the Netherlands at the time, and both of our visas were about to expire. Right before coming back to Beirut, we worked together on a cultural project with Mediamatic. We got comfortable working together and thought, Why not start a studio when we get back to Beirut? And so we did.

Book cover design and guidelines for Hachette Antoine, a regional publishing house that maajoun has been working with for over three years (Large preview)

When we started, we were highly inspired by Dutch business models, such as Mediamatic and O.K. Parking, which often initiate their own cultural or educational projects and events, sometimes funded through their commercial practice. This business model was somewhat new to us at the time. Things have changed since then, and many design agencies nowadays have their own cultural or educational projects, sometimes referred to as “R&D” or “corporate social responsibility”. Far from being a corporate strategy, we like to think of our side projects as a channel to exchange knowledge with other designers in our area.

Our commercial practice, on the other hand, is focused on editorial design, lettering and type design. Our studio is rather small (most of the time, only the two of us), which means we both have to do a bit of everything, even accounting!

Q: What have been your biggest achievements till now?

Khajag: I consider maajoun to be one of my biggest achievements to date. I love what we do. When you work on fun projects in university (whether cultural or experimental), everyone tries to make you feel like you should enjoy it as much as you can because you won’t get to do much of it in the “real world.” That’s not true. At maajoun, we work on interesting projects, we take the time to experiment, and we have fun!

Publishing Arek with Rosetta would be another big achievement. Arek is the first typeface that I seriously developed, and I am really happy it is out there and available to the public.

Maajoun’s submission to GrAphorisms, a project initiated by SHS Publishing (Large preview)

Q: You’ve done some work on Arabic versions of logos for several Disney films. Are you able to share with us what that process has been like?

Khajag: Arabic logo adaptation is becoming more and more common in the Middle East and North Africa, whose markets big international brands are trying to reach. Disney is no exception. We were asked to design the Arabic versions of the logos for several Disney films, including Aladdin, The Lion King and Beauty and the Beast.

We usually start by analyzing the original logo, its visual characteristics and some distinctive shapes; most importantly, we try to extract some cultural references from the lettering technique used in the logo, whether it has a 1960s retro feel or some elegance in a classical serif. We then try to translate these both visually and conceptually to the Arabic. This helps us to create a logo that works well visually with its Latin counterpart, without compromising the essence of the Arabic script.

Maajoun’s adaptation of Disney logos to Arabic script (Large preview)

The Arabic adaptation for Disney’s Tangled (Large preview)

Q: Is there a way for readers to know what conferences you’ll be speaking at or attending, or workshops you’ll be organizing?

Khajag: Kristyan Sarkis, Lara and I decided a few months ago to start a series of Arabic lettering workshops, which we’ll try to carry to different cities every now and then. We started during Beirut’s Design Week in June 2013 and had another session in July. We are having another one around May in Beirut, so those who are interested can stay tuned to our Facebook page.

Also, the Khatt Foundation usually organizes a workshop on Arabic type design at Tashkeel in Dubai. I usually take part in this. It’s an intensive nine-day workshop. The first three days concentrate on Arabic calligraphy and lettering, while the next six days are on Arabic type design. I also usually announce these things through Twitter (@debakir and @maajoun) or through maajoun’s page on Facebook.

Q: What advice would you give to young readers out there who are interested in becoming a type designer?

Khajag: Go for it! But know that type design is not only about drawing letters. It involves research and a lot of technical work.

Related Resources

(il, al)

© Alexander Charchar for Smashing Magazine, 2014.

Frizz-Free JavaScript With ConditionerJS 0

Frizz-Free JavaScript With ConditionerJS

Setting up JavaScript-based functionality to work across multiple devices can be tricky. When is the right time to load which script? Do your media queries matches tests, your geolocation popups tests and your viewport orientation tests provide the best possible results for your website? ConditionerJS will help you combine all of this contextual information to pinpoint the right moment to load the functionality you need.

Before we jump into the ConditionerJS demo, let’s quickly take a look at the Web and how it’s changing, because it’s this change that drove the development of ConditionerJS in the first place. In the meantime, think of it as a shampoo but also as an orchestra conductor; instead of giving cues to musicians, ConditionerJS tells your JavaScript when to act up and when to tune down a bit.

Applying conditioner to guinea pigs results in very smooth fur.
As you can clearly see, applying conditioner to guinea pigs results in very smooth fur. Take a moment and imagine what this could mean for your codebase.

The Origin Of ConditionerJS

You know, obviously, that the way we access the Web has changed a lot in the last couple of years. We no longer rely solely on our desktop computers to navigate the Web. Rather, we use a wide and quickly growing array of devices to get our daily dose of information. With the device landscape going all fuzzy, the time of building fixed width desktop sites has definitely come to an end. The fixed canvas is breaking apart around us and needs to be replaced with something flexible — maybe even something organic.

What’s a Web Developer to Do?

Interestingly enough, most of the time, our content already is flexible. The styles, visuals and interaction patterns classically are rigid and are what create challenging to downright impossible situations. Turns out HTML (the contents container) has always been perfectly suited for a broad device landscape; the way we present it is what’s causing us headaches.

We should be striving to present our content, cross-device, in the best possible way. But let’s be honest, this “best possible way” is not three-width based static views, one for each familiar device group. That’s just a knee-jerk reaction, where we try to hang on to our old habits.

The device landscape is too broad and is changing too fast to be captured in groups. Right this moment people are making phone calls holding tablets to their heads while others are playing Grand Theft Auto on their phones until their fingers bleed. There’s phones that are tablets and tablets that are phones, there’s no way to determine where a phone ends a tablet starts and what device might fall in between, so let’s not even try.

Grouping devices is like grouping guinea pigs.
Grouping devices is like grouping guinea pigs; while it’s certainly possible, eventually you will run into trouble.

To determine the perfect presentation and interaction patterns for each device, we need more granularity than device groups can give us. We can achieve a sufficient level of detail by looking at contextual information and measuring how it changes over time.

Context On The Web

The Free Dictionary defines “context” as follows:

“The circumstances in which an event occurs; a setting.”

The user’s context contains information about the environment in which that user is interacting with your functionality. Unlike feature detection, context is not static. You could be rotating your device right now, which would change the context in which you’re reading this article.

Measuring context is not only about testing hardware features and changes (such as viewport size and connection speed). Context can (and is) also influenced by the user’s actions. For instance, by now you’ve scrolled down this article a bit and might have moved your mouse a few pixels. This tells us something about the way you are interacting with the page. Collecting and combining all of this information will create a detailed picture of the context in which you’re currently reading this content.

Correctly measuring and responding to changes in context will enable us to present the right content in the right way at the right moment.

Note: If you’re interested in a more detailed analysis of context, I advise you to read Designing With Context by Cennydd Bowles.

Where And How To Measure Changes In Context

Measuring changes in context can easily be done by adding various tests to your JavaScript modules. You could, for example, listen to the resize and scroll events on the window or, a bit more advanced, watch for media query changes.

Let’s set up a small Google Maps module together. Because the map will feature urban areas and contain a lot of information, it should render only on viewports wider than 700 pixels. On smaller screens, we’ll show a link to Google Maps. We’ll write a bit of code to measure the window’s width to determine whether the window is wide enough to activate the map; if not, then no map. Perfect! What’s for dinner?

Don’t order that pizza just yet!

Your client has just called and would like to duplicate the map on another page. On this page, the map will show a less crowded area of the planet and so could still be rendered on viewports narrower than 700 pixels.

You could add another test to the map module, perhaps basing your measurement of width on some className? But what happens if a third condition is introduced, and a fourth. No pizza for you any time soon.

Clearly, measuring the available screen space is not this module’s main concern; the module should instead mostly be blowing the user’s mind with fantastic interaction patterns and dazzling maps.

This is where Conditioner comes into play. ConditionerJS will keep an eye on context-related parameters (such as window width) so that you can keep all of those measurements out of your modules. Specify the environment-related conditions for your module, and Conditioner will load your module once these conditions have been met. This separation of concerns will make your modules more flexible, reusable and maintainable — all favorable characteristics of code.

Setting Up A Conditioner Module

We’ll start with an HTML snippet to illustrate how a typical module would be loaded using Conditioner. Next, we’ll look at what’s happening under the hood.

<a href=",3.822"
   data-conditions="media:{(min-width:30em)} and element:{seen}"> … </a>

Codepen Example #1

We’re binding our map module using data attributes instead of classes, which makes it easier to spot where each module will be loaded. Also, binding functionality becomes a breeze. In the previous example, the map would load only if the media query (min-width:30em) is matched and the anchor tag has been seen by the user. Fantastic! How does this black magic work? Time to pop open the hood.

See the Pen ConditionerJS – Binding and Loading a Map Module by Rik Schennink (@rikschennink) on CodePen.

A Rundown of Conditioner’s Inner Workings

The following is a rundown of what happens when the DOM has finished loading. Don’t worry — it ain’t rocket surgery.

  1. Conditioner first queries the DOM for nodes that have the data-module attribute. A simple querySelectorAll does the trick.
  2. For each match, it tests whether the conditions set in the data-conditions attribute have been met. In the case of our map, it will test whether the media query has been matched and whether the element has scrolled into view (i.e. is seen by the user). Actually, this part could be considered rocket surgery.
  3. If the conditions are met, then Conditioner will fetch the referenced module using RequireJS; that would be the ui/Map module. We use RequireJS because writing our own module loader would be madness — I’ve tried.
  4. Once the module has loaded, Conditioner initializes the module at the given location in the DOM. Depending on the type of module, Conditioner will call the constructor or a predefined load method.
  5. Presto! Your module takes it from there and starts up its map routine thingies.

After the initial page setup has been done, Conditioner does not stop measuring conditions. If they don’t match at first but are matched later on, perhaps the user decides to resize the window, Conditioner will still load the module. Also, if conditions suddenly become unsuitable the module will automatically be unloaded. This dynamic loading and unloading of modules will turn your static Web page into a living, growing, adaptable organism.

Available Tests And How To Use These In Expressions

Conditioner comes with basic set of tests that are all modules in themselves.

  • “media” query and supported
  • “element” min-width, max-width and seen
  • “window” min-width and max-width
  • “pointer” available

You could also write your own tests, doing all sorts of interesting stuff. For example, you could use this cookie consent test to load certain functionality only if the user has allowed you to write cookies. Also, what about unloading hefty modules if the battery falls below a certain level. Both possible. You could combine all of these tests in Conditioner’s expression language. You’ve seen this in the map tests, where we combined the seen test with the media test.

media:{(min-width:30em)} and element:{seen}

Combine parenthesis with the logical operators and, or and not to quickly create complex but still human-readable conditions.

Passing Configuration Options To Your Modules

To make your modules more flexible and suitable for different projects, allow for the configuration of specific parts of your modules — think of an API key for your Google Maps service, or stuff like button labels and URLs.

Configuring guinea pig facial expression using configuration objects.
Configuring guinea pig facial expression using configuration objects.

Conditioner gives you two ways to pass configuration options to your modules: page- and node-level options. On initialization of your module, it will automatically merge these two option levels and pass the resulting configuration to your module.

Setting Default Module Options

Defining a base options property on your module and setting the default options object are a good start, as in the following example. This way, some sort of default configuration is always available.

// Map module (based on AMD module pattern)

    // constructor
    // element: the node that the module is attached to
    // options: the merged options object
    var exports = function Map(element,options) {


    // default options
    exports.options = {

    return exports;

By default, the map is set to zoom level 5 and has no API key. An API key is not something you’d want as a default setting because it’s kinda personal.

Defining Page-Wide Module Options

Page-level options are useful for overriding options for all modules on a page. This is useful for something like locale-related settings. You could define page-level options using the setOptions method that is available on the conditioner object, or you could pass them directly to the init method.

// Set default module options

// Initialize Conditioner

In this case, we’ve set a default API key and increased the default zoom level to 10 for all maps on the page.

Overriding Options for a Particular Node

To alter options for one particular node on the page, use node-level options.

<a href=",3.822"
   data-options='{"zoom":15}'> … </a>

Codepen Example #2

For this single map, the zoom level will end up as 15. The API key will remain 012345ABCDEF because that’s what we set it to in the page-level options.

See the Pen ConditionerJS – Loading the Map Module and Passing Options by Rik Schennink (@rikschennink) on CodePen.

Note that the options are in JSON string format; therefore, the double quotes on the data-options attribute have been replaced by single quotes. Of course, you could also use double quotes and escape the double quotes in the JSON string.

Optimizing Your Build To Maximize Performance

As we discussed earlier, Conditioner relies on RequireJS to load modules. With your modules carefully divided into various JavaScript files, one file per module, Conditioner can now load each of your modules separately. This means that your modules will be sent over the line and parsed only once they’re required to be shown to the user.

To maximize performance (and minimize HTTP requests), merge core modules together into one package using the RequireJS Optimizer. The resulting minimized core package can then be dynamically enhanced with modules based on the state of the user’s active context.

Carefully balance what is contained in the core package and what’s loaded dynamically. Most of the time, you won’t want to include the more exotic modules or the very context-specific modules in your core package.

Try to keep your request count to a minimum — your users are known to be impatient.
Try to keep your request count to a minimum — your users are known to be impatient.

Keep in mind that the more modules you activate on page load, the greater the impact on the CPU and the longer the page will take to appear. On the other hand, loading scripts conditionally will increase the CPU load needed to measure context and will add additional requests; also, this could affect page-redrawing cycles later on. There’s no silver bullet here; you’ll have to determine the best approach for each website.

The Future Of Conditioner

A lot more functionality is contained in the library than we’ve discussed so far. Going into detail would require more in-depth code samples, but because the API is still changing, the samples would not stay up to date for long. Therefore, the focus of this article has been on the concept of the framework and its basic implementation.

I’m looking for people to critically comment on the concept, to test Conditioner‘s performance and, of course, to contribute, so that we can build something together that will take the Web further!

(al, ml, il)

© Rik Schennink for Smashing Magazine, 2014.

Freebie: Flat Icon Set (60 Icons, PNG, SVG, EPS, PSD, AI) 0

Freebie: Flat Icon Set (60 Icons, PNG, SVG, EPS, PSD, AI)

Crafted with great attention to detail, today’s icon set is extremely easy to use and will most probably be the next ultimate resource for any of your design projects. This set of round icons was thoroughly designed by the creative team at Roundicons and has been released exclusively for Smashing Magazine and its readers.

This freebie contains 60 icons that have been designed in both round and flat styles, and can be used for free without any restrictions and serve various design purposes. Feel free to modify the size, color or shape of the icons, and use the icons in your commercial as well as your personal projects. No attribution is required, however, reselling of bundles or individual pictograms is not allowed.

The colors have been chosen with care to ensure maximum harmony when multiple icons are used on the same page, and can also be used in your mobile applications as well as in templates and themes. (Large preview)

The icons come in various file formats, which makes them very easy to use. Also, each icon is a flat illustration that can either be used in its circular container or as a standalone illustration. (Large preview)

A preview of each icon included in the icon set, with and without rounded containers. (Large preview)

Download The Icon Set For Free!

Insights From The Designers:

“Ever since the launch of our first 1000 flat icons, we received great feedback which encouraged us to further refine the icons, add more features, provide more formats and most importantly, produce many new icons. It is a true challenge attempting to cover all subjects and actions while trying to keep the illustrations simple enough to work as “icons” — a challenge we love!

We’ve received requests for over 800 different icons and have now successfully produced 500 of them for our first update. New ideas keep arising, so bear with us and stay tuned!”

Thank you, dear Roundicons team, for this fantastic icon set! We sincerely appreciate your time and efforts!


© The Smashing Editorial for Smashing Magazine, 2014.

Desktop Wallpaper Calendars: April 2014 0

Desktop Wallpaper Calendars: April 2014

We always try our best to challenge your artistic abilities and produce some interesting, beautiful and creative artwork. And as designers we usually turn to different sources of inspiration. As a matter of fact, we’ve discovered the best one—desktop wallpapers that are a little more distinctive than the usual crowd. This creativity mission has been going on for six years now, and we are very thankful to all designers who have contributed and are still diligently contributing each month.

This post features free desktop wallpapers created by artists across the globe for April 2014. Both versions with a calendar and without a calendar can be downloaded for free. It’s time to freshen up your wallpaper!

Please note that:

  • All images can be clicked on and lead to the preview of the wallpaper,
  • You can feature your work in our magazine by taking part in our Desktop Wallpaper Calendars series. We are regularly looking for creative designers and artists to be featured on Smashing Magazine. Are you one of them?


Designed by Aleksandra Kucher from Ukraine.


Sweet April Showers Do Bring May Flowers

“Discover the seasonal fruits and vegetables in April: artichoke and beans walking in the rain!” — Designed by Vitaminas Design from Spain.

Sweet April showers Do bring May flowers

Good Day

“Some pretty flowers and spring time always make for a good day.” — Designed by Amalia Van Bloom from the United States.

good day

Have A Smashing Easter!

“Easter is the only time of the year when it’s perfectly safe to put all your eggs in one basket… even the craziest ones” — Designed by Marielle Perikly Kokosidou from Greece.

Have a Smashing Easter!

Happy Easter

“Easter Bunny is kind of confused. He was very surprised when silly chicks popped out of these colorful eggs! Happy Easter from team.” — Designed by team from Brooklyn, NY.

Happy Easter


“…and enjoy your Easter holidays with some good chocolate.” — Designed by Ricardo Gimenes from Brazil.


April Cosmos

“I was inspired by a non-fiction book The Living Cosmos written by University of Arizona professor of astronomy Chris Impey. It’s a research of scientists trying to address the questions we ask about nature. Is there life in the universe beyond the Earth?” — Designed by Paul Ranosa from the Philippines.

April Cosmos

April Fool’s Day

“April Fool’s Day is harmless fun and a great way to get a new month kick started. The spring colors welcome the new season, while the pranks steal the stage. Our favorite is the Whoopie Cushion. It gets a laugh every time.” — Designed by Clarity Creative Group from Orlando, FL.

April Fool's Day

The Pablo Neruda’ s Spring

“I love this phrase that is referred to when we have a dream, nothing can stop us.” — Designed by Verónica Valenzuela from Spain.

The Pablo Neruda' s Spring

Dark Pastel

“A combination of gloomy spring showers and Easter.” — Designed by Matt Noa from the United States.

Dark Pastel

Earth Day!

Designed by Brandi Redd from the United States.

Earth Day!

Flying On A Rainy day!

“April is the month of spring or autumn depending where you live on the globe! It’s also the second rainiest month of the year. I was inspired by one simple motif to illustrate rain, birds and flowers. So either you witness rainy days or colorful ones … Enjoy April!” — Designed by Rana Kadry from Egypt.

Flying on a rainy day!

April Showers

“April showers bring May flowers.” — Designed by Travis Bellinghausen from the United States.

April Showers

  • preview
  • with calendar: 640×960, 1024×768, 1280×800, 1280×1024, 1440×900, 1920×1200, 2560×1440
  • without calendar: 640×960, 1024×768, 1280×800, 1280×1024, 1440×900,
    The Mystery Is Resolved: A Story Of Muffin Crumbs, Shady Characters And Invisible Letters 0

    The Mystery Is Resolved: A Story Of Muffin Crumbs, Shady Characters And Invisible Letters

    We’ve all been there, haven’t we? You find yourself in a coffee shop abroad, sipping cappuccino and chomping a muffin as you realize that your laptop’s battery charge is just about to crush your creative session to dust. Well, perhaps you’ve got your power adapter with you but, of course, it isn’t the right one for foreign power sockets.

    So you end up looking around and chatting up with strangers asking for help. Some are more responsive than others, and before you know it, you don’t just have a full battery, but you’ve made a couple of new, surprisingly interesting acquaintances.

    As it turns out, forgetting your power adapter is not only a great way to meet fantastic people but also a great strategy to come up with original ideas. In fact, this is exactly how the idea for the new Smashing Riddle was born—in a coffee shop in Zürich, Switzerland—and yes, it was indeed that cinnamon muffin that made all the difference in the end.

    Letters Scattered All Over The Place, Like Muffin Crumbs

    Animations have a way of drawing attention to themselves. So it’s understandable that a vibrant animated GIF might raise some interest, questions, or perhaps the reasonable concern of friendly strangers. Desperately looking for a charger, I sparked a number of awkward conversations with surprisingly unsurprised, friendly strangers around me.

    In the end, as the charger issue was successfully resolved, I found myself sitting behind a large wooden desk, immersed in a profound discussion with a charming, smart math student from Switzerland, and an eager, seasoned engineer from Turkey. It was a fast-paced, inspiring discussion about life stories, experiences, biggest failures and creative endeavours.

    This is how it all started. The letters scattered all over the GIFs were inspired by muffin crumbs scattered all over a plate. (Image source: jentilley)

    As the conversation continued—still sipping those Zürich cappucinos—I caught glimpses of one of the older animated GIFs looping on my screen, and before I knew it, the conversation was all about mysteries, riddles and mischievous animated GIFs. During an intensive, unscheduled, battery-recharge brainstorming session, we came up with a number of interesting ideas, all thoroughly written down, tagged and ready for use. One of the ideas was to play with the letters and the way they would be displayed.

    You see, at SmashingMag, we cherish the idea of lasting traditions—be it monthly desktop wallpapers, editorial newsletters or those weird mystery riddles. So in the spirit of tradition, the riddle obviously had to be based on animated GIFs, but we wanted to do something entirely different from changing file names or guessing Twitter handles.

    Originally, before my trip to Zürich, we had thought about using a number of invisible semi-transparent “layers” hidden in animated GIFs (erm, hey, we actually should do it for the next one!), and later on we spent quite some time prototyping the “reflection” idea in which a hidden message would be revealed once an actual mirror was placed up against the screen. The latter proved to be quite difficult later on in implementation, especially due to the wide diversity of screens out there.

    During the brainstorming session, we came up with an idea to do something along the lines of Scrabble, so the readers would derive clues from a number of GIFs and construct a secret keyword out of the letters discovered in those GIFs. And what if letters were scattered all across the GIFs very much like the crumbs of the muffin were scattered all across my plate? Some letters could be hidden, others would be clearly visible, and all of them would be turned, or flipped, or rotated, or skewed for confusion—very much in the spirit of the “reflection” idea we had in the beginning. That’s one of the ideas I brought back to the office after my trip to Zürich.

    A New Mystery, A New Design Challenge

    Our previous mysteries required a lot of tinkering and experimentation but, frankly, quite a bit of luck as well. The most important bit was to come up with the right approach. For the new riddle, we wanted to keep things a bit simpler and apparently easier to draw in as many readers as possible without the riddle becoming too annoying after the first few tries.

    Of course, the riddle shouldn’t be too easy either, so instead of hiding letters of one single word in GIFs, we felt that hiding parts of a sentence might work a bit better. We needed a twist though, something that would make the riddle a bit more interesting and cause one or two “Aha!” moments. We thought about using lowercase symbols to introduce more confusion but ‘i’ and ‘l’ might look too similar in a small resolution, so instead we looked specifically for letters that could be confusing and decided to rotate them or skew them until they actually become confusing. It wasn’t the only twist though, as you’ll see later in the article—a few fine adjustments and twists were added during the test phase later on.

    Whenever a new mystery is created, the first thing we do is set up the scene for the riddle. Our dear animator Guillaume knows exactly how to create just the right atmosphere. An early draft. (Large preview)

    So when Paul Boag’s new book was about to be published, we jumped right into the idea, came up with a sentence and scattered parts of that sentence across three animated GIFs. Each GIF contained a few scattered letters (all uppercase) that readers were supposed to use to build words. Once you put the words from all the GIFs together, you’d be able to create a sentence—and, of course, no letters should be left unused. So once the sentence is constructed, it had to be tweeted @smashingmag using the hashtag #smashing. Of course, we’d also hidden a few clues in the image captions under each animation and in the corresponding file names.

    Easy-peasy? Well, let’s see how it works, and what hidden clues those weird animations contain. (But seriously, who would put skewed letters on the floor and walls anyway, right?)

    1. “Change”: Get Out Of That Desk Already

    You know it, and we know it: nothing is more frustrating than stubborn management. Usually, changing workflows, processes and culture seems to be impossible, but perhaps something can be done about it after all. At least if you trust the hint provided for the very first animated GIF.

    Smashing Book Mystery
    Nothing is more frustrating than stubborn management. Perhaps it’s just about time to do something about it. Three words, one of them on the floor. (Large preview)

    Well, if you are playing Scrabble or any other word-building game, the first thing you have to do is gather everything you’ve gotc. So alright, we have to find three words in the GIF. Let’s collect the letters first, starting from the left-bottom corner:


    Alright. Well, we are smart, so why don’t we just use an online anagram solver to make the sense of these letters? We don’t want to do it manually, right? Hmmmm. No result. It doesn’t make sense. That’s weird. There must be a trap. Perhaps we are missing something: we could argue about “O”, if it’s actually the letter ‘O’ or the digit ’0′, but apparently we can rule out digits since all characters are supposed to be uppercase letters. But wait a second: if you rotate “Z” through 90 degrees, you end up with an “N”, right? So perhaps the combination is different:


    Ah, that’s better. Looks more like English. We’d better watch out for those traps. Okay, if we play around with it, we can figure out that the word hidden here is… NORDIC TEU, erm, TCRIONDUCE, er… aha! INTRODUCE! Nailed it.

    Okay, it wasn’t too hard. So what about the two missing words? Same game, same rules. Let’s collect the letters first:


    Mmm. Wait, wait. Only letters are allowed, so the yellow sticky notes with an equals sign and the dash are probably another trap since only uppercase letters have to be considered. We can remove them:


    Okay, it smells… easy. Probably the best way to avoid mistakes in discovering the words is to move letters around until they start making sense, probably with CMD+X and CMD+V. Right, right. The shiny new book on the table can’t just sit there on its own—what’s the title again? Digital Adaptation. Ah wait; wouldn’t “DIGITAL” fit nicely here, and in fact, the letters are right there, aren’t they?


    Well, it’s time to do something about that frustration, right? Probably just the right time for a… change?


    Bingo! Well, at this point we know that every animated GIF contains a couple of words, but it looks like they might be connected on their own as well. We might try to distribute the letters in an other way, but this solution does look quite fitting. Okay, let’s hope for the best and move to the next one.

    2. “Convincing”: They Listen But Don’t Move

    Well, perhaps you still have the enthusiasm to convince your colleagues about a more pragmatic, effective workflow. But is it really usually colleagues who need this kind of convincing?

    Smashing Book Mystery
    It’s difficult to convince them, though. But if not you, who else will help the company and bring it on the right path? Three words. (Large preview)

    Oh well, at least it looks like those people in the meeting are paying attention to what that guy is so passionately explaining. Again, let’s collect the letters scattered over the table first, and we should keep the variations in mind as well: “M” could be a “W” and “Z” could be an “N”, and “L” in left upper corner looks surprisingly similar to a skewed “J” (by design or by mistake?). So we’ve got:


    Oh wait, there is another one, in the upper left corner under the plant! Is it “M” or “W”? Let’s consider both options. Okay, that’s freaky:


    That’s quite a few combinations. We must be smarter about this. Let’s look at the image caption. The caption talks about “convincing them”, but what does it refer to? Ah, stubborn management from the first GIF. Perhaps the guy in the GIF is trying to convince… managers?


    Umm… almost. So we have neither “R” nor “S” here, so what else could it be? Ah! Perhaps management?


    Nice! Well, there aren’t many four-letter-words with “H”, “P” and “J”, so we probably should stick with the “L”. Could it be… HPLE, or to be more precise, HELP. Well, it sounds about right, especially since “help” is also mentioned in the image caption to that GIF.


    Invisible A
    The “A” was hidden fairly well in the pie chart on the presentation wall, wasn’t it?

    Good, good, it wasn’t too difficult after all. Oh snap. It was supposed to be three words. Did we miss something? Let’s take a closer look around the room again. The presentation chart has a few graphs on it, doesn’t it? Circles, bars, a pie… but that pie, there’s something suspicious about it! Doesn’t the piece of the pie look like an “A”? An invisible “A”, maybe? Well, it is…


    Alright! That’s a long shot, but let’s go with it for now, and let’s proceed with the last one.

    3. “Difference”: It’s Going To Be Just Fine

    Alright, we know how it works by now. Look closely everywhere on the image and gather all the letters first: that means looking on the carpet, under the chair and under the plant. And then double-check everything to make sure that we don’t miss anything. Also, we know that we can’t trust the colours and the position of letters, they didn’t help us in the past but instead confused (and annoyed) us a bit.

    Smashing Book Mystery
    In fact, you’ve got nothing to lose. And who knows, in the end, it might turn out even better than you expected. Four words. The letters on the floor belong together, in one word. (Large preview)

    We know that the words on the floor belong together, in one word. Let’s start with them:


    Oh well, there aren’t too many options here: it could be either “ERA” or “ARE”. Could it be that easy? Well, let’s keep it this way for now, and gather all the other letters, from the left to the right:


    And we have something that appears to be a blank piece of paper. What’s that thing now? An invisible character? Or a sign that a character is hidden? Or an empty space? Also, could something be hidden under the book, or behind the picture, or on the other side of the chair? OK, OK, let’s not get paranoid here. Deep breath. So we’ve got three words to figure out here.

    Well, it might take a while, so let’s watch out for clues. The guy in the chair seems to have it all figured out. Perhaps we should check the larger preview of the image. Oh snap, its file name is… difference.gif. Is it… could it be…?


    OK, this sounds about right. The combination of available unused letters doesn’t leave that many options: WEH KTEA, MATE HKE… Hmmm. Well, since the character in the chair is victorious, and it’s all about difference, perhaps he… made it?


    Better! We’re almost there:


    Invisible L
    Sometimes thumbs-up could mean more than a sign of appreciation. The invisible “L” that was missing to turn “REA” into the word “REAL”.

    Phew, now, that was quite a journey! But wait a second! That guy passing by, giving a thumbs-up to the character in the chair… Doesn’t it look like an “L”? The image caption says that the words on the floor belong together, but it doesn’t say that they build up an entire word. Well, if we added “L” to [ERA/ARE]… Oh:


    “REAL”! So perhaps it’s about making a real difference in the end. OK, let’s keep it in mind for now.

    Yes, of course, there might be many solutions and we would accept all of them if all letters were used, but after 45 minutes of collaborative brainstorming we discovered that it was highly unlikely that you could construct an entirely different, perfectly meaningful sentence by using all letters scattered across the GIFs, leaving no letters unused. Now it’s time to bring all these words together and try to construct something more or less meaningful out of it.

    “Solution”: Making Sense Of It All


    Okay, well, it doesn’t look too scary! It’s probably as easy as something along the lines of “Help the management introduce digital change: make real difference.” In fact, yes, we would accept all solutions which include “ERA” and “ARE”, but a sentence shouldn’t be just a loose pile of unconnected words. These are all the options which you could build out of this mess of letters:

    Livia Labate is one of the solvers of the riddle. Yep, it was a bit of work indeed.

    • Help the management introduce digital change: make a real difference.
    • Help management make the difference. Introduce digital. Change era.
    • Digital era: introduce a change, help management, make the difference.
    • Manage digital era change, introduce a plan, make the difference.

    So here we are. A little journey from muffin crumbs to letters scattered all over the place, shady characters and a few invisible characters. Time to reveal and reward the winners.


    It’s showtime! Surprisingly to us, the riddle didn’t take much less time to resolve than the previous ones. First place was earned by the person who was quickest and the closest to solving the riddle, i.e. have found all the right words in the riddle and leaving no letters unused. Please notice that since nobody discovered the “REAL” bit, we had to relax the rules a little. We raffled the other prizes across the first people who tweeted a correct sentence, and tried our best to exclude copycats. The winners can select any prize of their choice (be it a bag, a Smashing Library account, printed books or anything else). And they all get the Smashing Cody Stress-Relief Ball, too. All winners have been contacted.

    The first perfectly correct sentence with no letters left unused was tweeted by Dorin Moise from Brussels, Belgium, one hour and five minutes after the mystery went live, with: “there, make a difference: help management introduce digital change.” It’s not quite correct but it was the fastest and the most precise tweet. Congratulations, Dorin! You just won a roundtrip to our lovely hometown Freiburg for the Smashing Conference Freiburg, a stay in a fancy hotel and a few Smashing Books. Yaaay!

    And here are the other winners:

    • Paul Rose (1h 2min): “Make a difference, help management introduce digital change.”
    • Braunson Yager (1h 17min): “Help management make the difference, introduce the digital era.”
    • Charlie Park: “Introduce a digital era; help management make the change.”
    • Razvan (3h 21min): “Introduce digital change: help management make a difference there.”
    • Livia Labate (Washington DC, USA): “Help management introduce digital change: make a difference there!”
    • Eva Kavaliotou: “Help management make the difference. Introduce digital. Change era.”
    • Ed Hicks: “Digital era: introduce change, convince management, help make the difference.”
    • Andreas Busschop: “Make difference. Help introduce the digital management era.”

    Congratulations! And thanks to everyone who participated! We hope we didn’t waste too much of your productive work time (and didn’t cause too many headaches either).

    Behind The Scenes

    Guillaume Kurdjian
    Guillaume Kurdjian is a 22-year-old freelance illustrator and animator from Nantes, France. Guillaume likes to experiment with stuff on his computer and climb trees.

    Just like the last two times, we worked with talented Guillaume Kurdjian on a series of animated GIFs for the riddle. This time the discussion thread was a bit shorter, and after thorough conversations and prototypes, we ended up with quite a number of different GIFs, drafts, and ideas that were thrown away, as well as the ones that made it to the final stage.

    All designs were a series of iterations to make the overall riddle not necessarily perfect, but just right. So a big “thank you!” to Guillaume for following through and being so enthusiastic and kind about all the changes made.

    Ah, it is a great feeling to solve that damn riddle, isn’t it? Well, you don’t really make the difference, but it’s pretty, pretty good nevertheless. (Large preview)

    As it always is with a public hashtag, it can be quite difficult to separate between the “real” tweets and copies of the tweets. We didn’t choose the hashtag #smashing by accident since it is a quite “messy” hashtag on Twitter, but it wasn’t good enough since we saw lots of weird activities going on, with people reusing tweets 1:1 which we of course didn’t accept. We did look very closely at the dates and profile and activities of every winner to prevent copycats from winning. (We probably will go with #cats next time or even better—will challenge you to construct the “right” hashtag on your own).

    Poor frames on the wall must have quite a number of finger prints now; we’ll have to bring the room in order later. And yes, apparently those yellow stick-it notes were quite confusing indeed! (Large preview)

    The first GIF wasn’t really a problem for anyone. However, for some weird reason the word “convincing” started to pop up in tweets, although the letter “V” didn’t make its public appearance anywhere—in neither of all those GIFs. Quite a number of readers discovered “game plan” in the second GIF and was confused about the number of words that would be hidden in the second GIF if “game plan” actually was hidden there.

    Wordsmith encountered server hiccups 30 minutes after the riddle went live, but of course we don’t take any responsibility for it.

    The truth is that “game plan” wasn’t the part of our initial plan, so we take no responsibility for massive headaches or confusion caused—sorry about that!. Also, apparently Wordsmith encountered server hiccups 30 minutes after the riddle went live, but of course we don’t take any responsibility for it either.

    Semaphore, marine alphabet
    Sam Stealth-Geek Tremaine and his colleagues went as far as trying to decode the movements of the character speaking in front, using semaphore. (Image credit.)

    The most trouble was caused by the second GIF which caused quite a lot of headache for many readers. You could go as far as trying to decode the movements of the animated character who could be using semaphore, a marine alphabet. This wasn’t the plan either.

    Waiting for round 3 already?
    Are we waiting for round 4 already?

    So this is it! It was quite a journey, but we hope it was worth it. We are really sorry about all the unproductive hours that you spent solving the riddle. Well, kind of. Now, are you ready for the next round? 馃槈 Stay tuned!

    © Vitaly Friedman for Smashing Magazine, 2014.