MADCSS stands for Modular Attribute-Driven CSS. Yeah, sooo clever. Basic architecture is based on inspired by: AMCSS, Gemma, Organic CSS, Atomic Design and Tachyons.

The base global prefix for all attribute modules is i-, as in "interface".

↑ Naming things

Attribute names are defined in a simple fashion: attribute always starts with the global prefix, followed by module name. If it's a child, then it appends a double hyphen, followed by the child name. Both parent and child names are written with catepillar-case And try not going deeper than 2 levels with that: i.e. grandchildren and further are forbidden.

<prefix>-<parent-name>[--<child-name>]

Warning: uppercase letters in attribute names are invalid HTML and can cause bugs in some browsers (as most browsers tend to auto-fix that problem in your code).

Modifiers are a space-separated strings, so basically you can use any character you want (except space of course):

<div i-void--friedrich-nietzsche="2/3 isDead +_- żółć 鸡汤">…</div>

And then you would write something like this in your .(s)css file:

/* nietzsche module */
[i-void--friedrich-nietzsche] { all: unset; }
[i-void--friedrich-nietzsche~="2/3"] { all: unset; }
[i-void--friedrich-nietzsche~="isDead"] { all: unset; }
[i-void--friedrich-nietzsche~="+_-"] { all: unset; }
[i-void--friedrich-nietzsche~="żółć"] { all: unset; }
[i-void--friedrich-nietzsche~="鸡汤"] { all: unset; }

↑ Architecture

There are literally five mandatory files you need -- the rest are custom modules (you can delete existing ones, just don't tell me about it). Building new things happens in modules/ directory and you will define global variables in -- wait for it -- variables.css! GASP!

modules/
  nietzsche.css
  complex-thing/
    complex-thing.css
    complex-thing-part.css
    complex-thing-config.css
setup/
  root.css
  states.css
  typography.css
aggregate.css
variables.css

As for variables, make sure that you define module private ones in the :root {} block on top of the file. If multiple modules use a variable, you should put in in global file.

The setup/ dir contains some resets for the whole project and simple typography normalisations.

Modules can be either structure- and layout-related selectors that do one, generic thing extremely well -- or a context-specific selectors for distinct components of an interface. They can be naturally mixed with each other -- as long as it makes sense of course. And if you need a humongous module, create a separate modules/moduleName/ directory with same name as module and include all partials in modules/moduleName/moduleName.css file.

↑ Quirks and rules

1. Colors Purity -- the thing I am passionately crazy about: define new colors only inside variables.css to assure your design is not "50 shades of gray". Also try learning some proper words for naming them: like "amaranth" is much better than "redLight2".
2. The Leading Principle -- we want all of the elements, texts and empty spaces to be a multiplication of leading size (line-height of root element in CSS). That way, we assure things look beautiful and we avoid the issue of "50 shades of margins" (yes, I don't know much jokes).
3. Inverse Swiss Army knife -- avoid creating too diverse modules with plenty of modifiers, as it will be hell to maintain. In this instance I would prefer to make them a bit DRY instead. You can also try creating a "shared module" or go with some @mixin if you'd use SASS.