Molecular

Molecular abstracts long atomic CSS strings into reusable, tweakable Ruby objects. You get all the benefits of working with atomic CSS, without the ugly markup and verbose API.

Transform your app's views from this...

<a class="f6 link dim ph3 pv2 mb2 dib white bg-black" href="#0">
  A black button
</a>

<a class="f6 link dim ph3 pv2 mb2 dib red bg-black" href="#0">
  A red button
</a>

...into this:

<a class="<%= ui_button %>">A black button</a>

<a class="<%= ui_button.(color: 'red') %>">A red button</a>

• Installation
• Usage (Generic)
  • Step 1: Create a Compound
  • Step 2: Use your Compound in a view
  • Step 3 (optional): Tweak your style keys
• Usage (framework-specific)
  • Rails
  • Sinatra
  • Roda
• Development
• Contributing
• Related Projects

Add this line to your application's Gemfile:

gem 'molecular'

And then execute:

$ bundle

Or install it yourself as:

$ gem install molecular

You can use Molecular with any CSS framework, in any Ruby app. In broad strokes, here's how to style a button with Molecular, using example CSS classes from tachyons.css.

Somewhere in your app:

Button = Molecular.compound(
  color: 'white',
  bg: 'bg-black',
  base: 'f6 link dim ph3 pv2 mb2 dib',
)

Somewhere in an erb template:

<a class="<%= Button %>" href="#">
  A styled button
</a>
<a class="<%= Button.(color: 'yellow', bg: 'bg-blue') %>" href="#">
  A styled button that is yellow instead of white, with a blue background
</a>

<!-- renders as:
<a class="f6 link dim ph3 pv2 mb2 dib white bg-black" href="#">
  A styled button
</a>
<a class="f6 link dim ph3 pv2 mb2 dib yellow bg-blue" href="#">
  A styled button that is yellow instead of white, with a blue background
</a>
-->

The keys in the hash you pass to Molecular.compound(styles) determine which CSS classes you can easily substitute later.

In the button from Step 2, it would be easy to swap color or bg for different classes.

But if you wanted to replace any of the classes in the base key, you'd need to rewrite the whole base key from scratch:

<a class="<%= Button.(base: 'f4 link dim ph3 pv2 mb2 dib') %>" href="#">
  This was an awful lot of work just to change the font size :(
</a>

To make a more flexible Compound, use more granular styles hash:

Button = Molecular.compound(
  color: 'white',
  bg: 'black',
  size: 'f6',
  hover: 'link dim',
  padding: 'ph3 pv2',
  margin: 'mb2',
  display: 'dib',
)

<a class="<%= Button.(size: 'f3', padding: 'pa2', margin: nil) %>">
  This button was easier to tweak
</a>

If you skipped straight to this section from the TOC, make sure to read the generic usage section first!

These examples use Molecular and tachyons.css to style a button in Rails, Sinatra, and Roda.

• Rails
• Sinatra
• Roda

Step 1:

Import tachyons.css into your asset pipeline, either directly or via the [tachyons-rails gem][tachyons-gem]

Step 2:

Create a StyleHelper in app/helpers/style_helper.rb and build some compounds:

module StyleHelper
  def ui_button
    Molecular.compound(
      color: 'white',
      bg: 'black',
      size: 'f6',
      hover: 'link dim',
      padding: 'ph3 pv2',
      margin: 'mb2',
      display: 'dib',
    )
  end
end

Step 3:

Use your StyleHelper methods in your views:

<!-- app/views/welcome/index.erb -->
<a class="<%= ui_button %>">A styled button</a>
<a class="<%= ui_button.(bg: 'bg-blue') %>">A blue button</a>

Step 1:

Include the tachyons.css stylesheet somewhere in your app's layout.

Step 2:

Create a StyleHelper somewhere:

module StyleHelper
  def ui_button
    Molecular.compound(
      color: 'white',
      bg: 'black',
      size: 'f6',
      hover: 'link dim',
      padding: 'ph3 pv2',
      margin: 'mb2',
      display: 'dib',
    )
  end
end

Step 3:

Make your StyleHelper available to your app's helper methods:

require_relative 'wherever_you_put_it/style_helper'

class MyApp < Sinatra::Application
  helpers StyleHelper

  get '/' do
    erb :my_template
  end
end

Step 4:

Use your StyleHelper methods in your views:

<!-- views/my_template.erb -->
<a class="<%= ui_button %>">A styled button</a>
<a class="<%= ui_button.(bg: 'bg-blue') %>">A blue button</a>

Step 1:

Include the tachyons.css stylesheet somewhere in your app's layout.

Step 2:

Create a StyleHelper somewhere:

module StyleHelper
  def ui_button
    Molecular.compound(
      color: 'white',
      bg: 'black',
      size: 'f6',
      hover: 'link dim',
      padding: 'ph3 pv2',
      margin: 'mb2',
      display: 'dib',
    )
  end
end

Step 3:

Include StyleHelper in your app:

require_relative 'wherever_you_put_it/style_helper'

class MyApp < Roda
  plugin :render
  include StyleHelper

  route do |r|
    get('/') { view('stylish') }
  end
end

Step 4:

Use your StyleHelper methods in your views:

<!-- views/stylish.erb -->
<a class="<%= ui_button %>">A styled button</a>
<a class="<%= ui_button.(bg: 'bg-blue') %>">A blue button</a>

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/chrisfrank/molecular.

• Tachyons.css
• Nanostyled (JS)