scarab-carapace

Highly configurable framework for generating single-purpose, functional CSS classes

Carapace is a Sass framework which generates functional/atomic CSS classes based on user-defined configuration. It depends on the scarab-scss Sass utility library for low-level functions and mixins.

Although Carapace provides some defaults, it is not an opinionated CSS library. Think of it instead as a tool for rapidly creating custom CSS libraries on a per-project basis.

Table of contents

• Features
• Installation
• Configuration
  • Variable Management
  • Naming Convention
• Usage
  • Reset/Normalize
  • Modules
  • Compiling CSS
• Documentation
• Resources

Features

• Functional CSS (a.k.a. Atomic CSS)
• Configuration-driven stylesheets
• Bring-your-own naming convention
• Responsive and mobile-first
• Optional CSS reset/normalize
• Easily achieve vertical rythmn
• Automatic styleguides for your project (with scarab-styleguide)

Installation

1. Install scarab-carapace as a dev-dependency in your project via npm:

npm install scarab-carapace --save-dev

1. Add your node_modules folder to your Sass includePath.

2. Import the necessary files in your main stylesheet:

// IMPORTANT
// 
// Follow the import order below to ensure modules are generated properly.

@import 'scarab-carapace/core';      // Imports scarab-scss, core utils & config
@import 'custom/config.scss';        // Your custom Carapace settings & config
@import 'scarab-carapace/config';    // Imports default module config
@import 'custom/module-config.scss'; // Your custom Carapace module config
@import 'scarab-carapace/modules';   // Generates CSS classes

Configuration

The quickest way to get up to speed on configuring Carapace is by looking at the default configuration files.

Variable management

Carapace imports the scarab-scss utility library, exposing the get() function and set() mixin. These utilities allow you to configure the Carapace theme and modules. Refer to the Configuration section of the README in scarab-scss for more information on get() and set().

Naming convention

With the default naming convention, class names that Carpace generates will look something like this:

<section class="bgc:black c:white  m(bgc:white) m(c:black)  hv(c:grey) m(hv(c:dark-grey))">
	<p>This section has a 'black' background with 'white' text.
	When hovered, the text color changes to 'grey'.</p>
	<p>On 'medium'-sized screens, it has a 'white' background with 'black' text.
	When hovered, the text color changes to 'dark-grey'.</p>
</section>

Breakpoint and state shorthands and values can be configured in the breakpoints and states maps, while the selector format, prefixes and suffixes can be customized by changing the values of the following keys in $SCARAB:

• selector-format
• root-prefix
• root-suffix
• variant-prefix
• variant-suffix
• modifier-prefix
• modifier-suffix
• breakpoint-prefix
• breakpoint-suffix
• state-prefix
• state-suffix

Be sure to prefix any special characters in the selector-format, *-prefix and *-suffix values with a \, so that generated CSS class names are properly escaped.

Usage

Reset/Normalize

These styles are included by default. If you wish to turn them off, set the reset-styles and/or normalize-styles keys in $SCARAB to false.

Modules

Modules are single-purpose, functional CSS classes. Module class names and values are dynamically generated by Carapace, depending on the values set in the global $SCARAB variable.

Module class names consist of a root, and optionally: variant, modifier, breakpoint and state.

In Carapace, configuration for a module typically looks like this:

@include set-default( modules, 'opacity', (
  root        : 'o',                  // String which defines the module's `root`
  values      : get(opacity),         // Map  of `modifier` names to CSS property values
  states      : get-keys(states),     // List of `state` names
  breakpoints : get-keys(breakpoints) // List of `breakpoint` names
) );

Refer to the modules/ folder for more information on how to configure modules.

Compiling CSS

Carapace does not include a build step to compile Sass to CSS. The following tasks are recommended for production:

• Prefix compiled CSS for cross-browser compatibility (autoprefixer)
• Minify compiled CSS (cssnano)
• Separate base CSS from styles in media queries (sakugawa)
• Inline base CSS, and <link> media query styles

Documentation

Documentation is a work-in-progress.

Related

• scarab-scss — Sass utility framework for rapid stylesheet development
• scarab-styleguide — Generate automatic styleguides from scarab-carapace configuration
• scarab-cli — Command-Line Interface for the Scarab Sass ecosystem
• scarab-snippets — Sublime Text snippets for the Scarab Sass utility framework