[Cederfjard]

> Basically, it's just a naming convention which tells you something about the purpose of this particular class. In languages like Java, C#, etc. you also use naming conventions to communicate something useful. In CSS, I do the same thing. There is UpperCaseCamelCase, lowerCaseCamelCase, _withLeadingUnderscore, and x-prefixed. All of these things mean something specific.

What does those four styles mean then, respectively? I'm curious.

[ahoge]

Subtree root node, descendent, modifier, and not CSS.

A modifier changes one or several aspects to make it more suitable for a different purpose.

You can stick subtrees into the leafs of other substrees. There is no overlap or interweaving.

So, if you look at some node, you just travel the tree up until you hit the first UpperCaseCamelCase class. That's the structure this node belongs to. It's also the name of the partial.

E.g. this is the "bricks/_Pagination.scss" partial:

  /// Simple pagination for search results and similar things.
  ///
  /// <div class="Pagination">
  ///     <a href="#" class="active">1</a>
  ///     <a href="#">2</a>
  ///     <a href="#">3</a>
  ///     <a href="#">4</a>
  /// </div>

  .Pagination {
  	@include TopMargin;
  	text-align: center;
  	font-size: 0;
  	& > a {
  		background: lighten($lightBlue, 12.5%);
  		color: #fff;
  		display: inline-block;
  		width: $gap;
  		padding: $gapTiny 0;
  		text-decoration: none;
  		margin-left: $gapTiny;
  		font-size: $rootFontSize;
  		&.active {
  			background: $lightBlue;
  			cursor: default;
  		}
  		&:hover {
  			background: $lightBlue;
  		}
  		&:first-child {
  			margin-left: 0;
  		}
  	}
  }

The generated docs: http://i.imgur.com/YFbhWjj.png

If there are any modifiers, a preview (with one line description) will be generated for each of them.

Apart from the reset/normalization and base styles, everything looks like that.

[Isofarro]

You have an accessibility issue in your example markup. Having links adjacent to each other without either non-linked readable characters, or an appropriate markup structure leads to screen readers reading out the numbers 1 2 3 4 in a "linked" tone, and it is impossible to distinguish that from a single link containing all four numbers.

That's why the web development best practice here is to mark up a list of links with a list. And before we had web standards people used to separate adjacent links with the | character, so at least screen readers would have the numbers read out in a link voice, and the 'bar' read out in a non-linked voice.

If your intention is to create reusable components, then it's essential that you're not introducing accessibility issues by default.

There's a second accessibility issue with the pagination. Why is the active page a link? What does it link to, considering that you are already in the view that should be that page. That feels like a link that does nothing. For a generic pagination, this feels like another accessibility issue to trip up developers.

Also, there's the obvious anti-pattern of using # as the href, instead of an actual URL. That leads to developers assuming that everything is handled with JavaScript. It's easy to fix in documentation, by putting in realistic looking URLs in there.

Good examples of documentation are ones that demonstrate good practice, and not encourage bad habits.

I know, good documentation is not easy. That's why we have to be careful of falling into these sorts of pitfalls. Especially when developers have no choice but to rely on documentation being correct.

[ahoge]

> If your intention is to create reusable components [...]

This isn't like Bootstrap, mind you. It's a set of building blocks for one particular website.

> Also, there's the obvious anti-pattern of using # as the href, instead of an actual URL.

It's about the structure of the markup. "#" is used as no-op href for dummy links. "data:," is used as no-op src for dummy images.