Add "Component Structure" section to guidelines

[davidkpiano]

One thing that would be tremendously useful in the guidelines is how to actually organize the content of a component file, e.g. components/_buttons.scss. I've tended towards this (opinionated) structure:

• Variables - component-specific variables (whether singular variables or maps) to prevent magic numbers
• Functions - any component-specific functions, if applicable
• Mixins - component-specific, if applicable for dynamically generating variations of the component (not necessary in many cases, if few variations exist)
• Structures - the CSS component layout/structure, excluding any non-layout rules, such as color
• Relationships - any component-specific CSS with regard to relationships (via combinators) with other components
• Themes - thematic CSS for non-layout component styling, such as background, colors, shadows, etc.
• Exports - the manifested CSS classes, if they are to be exposed

Here is how a component-specific file would look with this structure, with a button component as an example:

// Variables
$button-color: blue;
$button-width: 5rem;
// ... etc.

// Functions
// ... not applicable for buttons. Can remove this section.

// Mixins
@mixin button-theme($color: $button-color) {
  background-color: $color;
  // ... etc.
}

// Structure
%button {
  display: block;
  width: $button-width;
  // ... etc.
}

// Relationships
%button {
  %buttonGroup > & {
    display: inline-block;
    // ... etc.
  }
}

// Themes
%button {
  @include button-theme($color: $button-color);

  &-secondary {
    @include button-theme($color: gray);
  }
}

// Exports
.my-button {
  @extend %button;

  &.secondary {
    @extend %button-secondary;
  }
}

If you don't want to use placeholders in the guidelines, these can easily be subbed out for classes. I use placeholders above for a couple reasons:

• Resilience to nomenclature change. If class names change, they only need to be changed in one place - in the Exports section.
• Ability to "remove" from output CSS without side effects. If %foo component extends %bar component, but I decide to remove the .bar class, neither %foo nor .foo will be affected.

Other considerations:

• Structure, relationship, and themes, still in that order, but within the same parent placeholder instead of having to be nested 3 different times? I can go either way.
• Should we add States to this organization? In the above structure, that would include %button-disabled, %button-focus, etc.

Let me know what you think! In the past, I've had each of these sections in different files, but I'm moving towards having them in a single file, with an enforced order and organization.

[KittyGiraudel]

Very interesting idea David. I think this deserve a whole section, hence will be added in 1.1, probably in a while from now (with Sass 3.5 or something). This gives us time to write something nice and everything. :)

[davidkpiano]

Sounds good!

[KittyGiraudel]

Maybe 1.3.0. :)

[KittyGiraudel]

Would you be interested in tackling this David?

[davidkpiano]

@hugogiraudel Sure!

[KittyGiraudel]

For the record, #292 has been started. :)

[davidkpiano]

Okay. I'll have a first draft to you this weekend.

[KittyGiraudel]

Will be released in 1.3.0.