Home

Developer documentation

This wiki is intended for developers/contributors of the atomic.css tool repository.

Quick CSS glossary:

selector {  property: value  }
            ↑ declaration ↑
         ↑ declaration block ↑
↑__________ rule or ruleset _↑

Atomic.css generation:

The generation process involves 2 main parts:

1. Rules & Helpers: All CSS rules available in Atomic CSS. Atomic rules will map to valid standards-compliant CSS properties. Helpers are rules not related to a single CSS property but it usually bundles some useful features you will repeteadly find in common CSS constructs (e.g. Cf for clearfix, Hidden to visually hide content from sighted users but available to screen-readers, LineClamp and Ellipsis to add ellipsis to lines of text). Both rules and helpers follow the same syntax, a simple object containing the following keys:

Key	Description	Required	Default
type	Either helper or pattern	Yes	undefined
name	Name of the rule/helper	Yes	undefined
matcher	The portion of the CSS class that maps to the unique identification of the class	Yes	undefined
noParams	If the class doesn't require params, this should be set to true. Only useful to helpers.	No	false
style	A CSS object where keys are CSS properties and values are CSS values. If a param is used you can retrieve it using $ + <index>.	Yes	undefined
arguments	An array of objects used to define predefined values for the class. Each index in the array maps to the arguments passed. For each object, keys are names given to the predefined values and values are the CSS values of the predefined value. See example below.	No	undefined
rules	Additional CSS rules you want to add when this class is used.	No	`undefined

Examples:

{
    "type": "pattern",
    "name": "Box sizing",
    "matcher": "Bxz",
    "allowParamToValue": false,
    "styles": {
        "box-sizing": "$0"
    },
    "arguments": [{
        "cb": "content-box",
        "pb": "padding-box",
        "bb": "border-box"
    }]
}

{
    "type": "helper",
    "name": "Clearfix",
    "matcher": "Cf",
    "noParams": true,
    "styles": {
        "zoom": 1
    },
    "rules": {
        ".Cf:before, .Cf:after": {
            "content": "\" \"",
            "display": "table"
        },
        ".Cf:after": {
            "clear": "both"
        }
    }
}

2. Configuration: This is the actual source of truth for Atomizer when creating the CSS. It is a simple JS object containing 4 keys: custom, breakPoints, classNames, and exclude. The configuration file will come from the consumer of atomizer. It can be manually passed, automatically generated after scanning files or a mix of both (e.g. Manually create a config file, define some custom classes, and let the tool find the classes in my project and merge the results in a final config output). Please note that classes defined in custom won't be generated in the final CSS unless they are used (passed in classNames). Please see example config file as it contains useful comments to understand what each key does.

Example: https://github.com/yahoo/atomizer/blob/master/examples/example-config.js

Pull Requests

Pull requests must pass unit tests and must make sense for the atomic.css. The core contributors will comment and request updates if necessary. Once everything looks good, the pull request will be merged to master and available for the next release.

Release Cycle

Atomic.css package has a weekly release cycle that will include all the pull requests merged to master since last release. If no updates were made, the release will be skipped to the following week. Releases will be done every Monday. A release note will be included listing all the changes done to the package. Some releases may go out any other day of the week depending on its urgency.

Versioning

The tool follows Semver 2.0.0 versioning. Make sure you always lock the versioning on the major version (e.g. ~1.1.0). If a class name changes, the Major version will be bumped so you are aware that by upgrading to it will cause class names to break.