Primary Mixin

[gvonkoss]

What

The primary mixin is a single mixin that can style all variations and features of a component.
The concept of the primary mixin is made possible because we are taking steps to remove custom classes.
The preliminary specs that we have for this mixin is that it will take a $opts list, or map, depending on the component, which will either output all styling if called without any arguments:

@include oBottle(); // outputs all of the bottles known to personkind

or it will output granular styling depending on the options passed in, e.g.:

@include oBottle($opts: (
    'type': 'Champagne',
    'size': 'Nebuchadnezzar'
)); 

/*
.o-bottle--champagne.o-bottle--nebuchadnezzar {
    // outputs styles for a 15L champagne bottle only  
}
*/

which can—depending on the component—accept a list of options:

@include oBottle($opts: (
    'type': ('Milk'),
    'size': ('250ml', '500ml'),
)); 

/* 
.o-bottle--milk {
    // outputs milk bottle
        .o-bottle--250ml {
            // outputs 250ml size
        }
        .o-bottle--500ml {
            // outputs 500ml size
        }
    }
}
*/

Why

We've discussed this amongst ourselves, and have listed out the following reasons:

• Simplification: Requiring a single mixin with options will allow the implementation of Origami components to be more straight forward, and will provide more clarity.
• Consistency: As this will be developed across all components, this should allow users of one component to understand another without having to understand multiple different mixins in order to style a component, if it is not required.
• Abstracting from silent mode: there will be no need to specify $o-component-is-silent, which causes unnecessary confusion, when we can call the primary mixin to do the same job. There have been discussions about working this into the build service, but that is an extra discussion for further down the line.

Exceptions

There are some components, such as o-typography, that will need more than one mixin. While the intention is for these to have a primary mixin to output default styles, they will also provide mixins to output custom styling. These mixins will allow custom classes, (an option which is not available to primary mixins) which is useful for building custom components.

Supporting Examples

The primary mixin has already been applied to the following components:

• o-table
• o-message

[wheresrhys]

For perf reasons users might want to output pieces of CSS as small as possible
For simplicity of API/implementation reasons, I can imagine there'd be pressure to minimize the number of options available.

Have you thought about how to approach this tradeoff?

[notlee]

Primary mixins are aimed at making Origami simpler to use, but we also hope they will contribute to smaller CSS bundles: By outputting the minimal styles needed for given component variations/features, encouraging the use of o-component class selectors rather than duplicate styles within custom classes, avoiding base styles for a component being output many multiple times, and helping minifiers tidy up if they are. In cases like o-buttons it's a really strong replacement to turning silent mode off (as some production apps do).

We've explored some of our more complicated components (like o-typography, o-buttons) and think the API can adapt sensibly.

It would be good to discuss with a concrete example, if you have one in mind?

[wheresrhys]

In o-buttons there are sizes, "primaryness", icons. If my site uses a large primary button with the close icon on it, will the options allow me to include just styles for that combination, or only go as fine grained as allowing e.g. primary buttons at all sizes, with or without all icon variants included?

Would it be instructive to sketch out what the o-buttons api would look like?

[notlee]

Here's our currently proposed interface for o-buttons in a PR. The PR has significant code changes but that's largely unrelated refactoring, so we're happy to change the interface based on feedback. :)

[wheresrhys]

lovely stuff

[notlee]

All Origami maintained components now have a primary mixin oComponentName. To close this issue I think this needs adding to the spec as a should. With the view to make it a must requirement if we release an Origami spec v2 so that we can retire the silent mode variable completely.

[JakeChampion]

All Origami maintained components now have a primary mixin oComponentName. To close this issue I think this needs adding to the spec as a should. With the view to make it a must requirement if we release an Origami spec v2 so that we can retire the silent mode variable completely.

@notlee, I'm happy with us adding this to the spec as a should for now. @Financial-Times/origami-core what do you all think?

[chee]

let's add it as a should. and if there's a spec v2 let's make it a spec v2.0.0 and semver the spec

[notlee]

Cool, done #163