ComponentContracts.md

Component Contracts

Component contracts define the shape of the markup for a component. Designers and developers can both work off of the contract, and tools can validate that both the CSS and HTML matches the contract.

Uses Block, Element, Modifier conventions.

Symbol Definition

These symbols may appear after a list of modifiers or an element in the contract. The default is to require exactly one of the declared element.

? = Zero or One
* = Zero or More
+ = One or More

Example Contract

Article (--breaking-news|--opinion)+        // BlockName (--available|--modifiers)
    __headline h1                           // 
    __subhead? h2                           // 
    __date                                  // 
    __byline                                // 
    __content                               //
        <>+                                 // One or more of anything.
    __updates?                              // 
        __update*                           //
            <>+                             //

Example Markup

<div class="Article Article--breaking-news">
    <h1 class="Article__headline">Component Contracts Invented!</h1>
    <h2 class="Article__subhead">Designers and Developers Rejoice</h2>
    <div class="Article Article--date">2018-2-23</date>
    <div class="Article Article--byline">Nate Roling</div>
    <div class="Article Article--content">
        <!-- anything can go here -->
    </div>
    <div class="Article Article--updates">
        <div class="Article Article--update*"><!-- anything can go here --></div>
    </div>
</div>

Example Selectors

.Article
.Article--breaking-news
.Article--opinion
.Article--breaking-news--opinion

.Article h1.Article__headline
.Article--breaking-news h1.Article__headline
.Article--opinion h1.Article__headline
.Article--breaking-news--opinion h1.Article__headline

.Article h2.Article__subhead
.Article--breaking-news h2.Article__subhead
.Article--opinion h2.Article__subhead
.Article--breaking-news--opinion h2.Article__subhead

.Article .Article__date
.Article--breaking-news .Article__date
.Article--opinion .Article__date
.Article--breaking-news--opinion .Article__date

.Article .Article__byline
.Article--breaking-news .Article__byline
.Article--opinion .Article__byline
.Article--breaking-news--opinion .Article__byline

.Article .Article__content
.Article--breaking-news .Article__content
.Article--opinion .Article__content
.Article--breaking-news--opinion .Article__content

.Article .Article__updates
.Article--breaking-news .Article__updates
.Article--opinion .Article__updates
.Article--breaking-news--opinion .Article__updates

.Article .Article__update
.Article--breaking-news .Article__update
.Article--opinion .Article__update
.Article--breaking-news--opinion .Article__update