Suggestion: migrating styleblocks into KSS comments

[lolmaus]

Initially i intended to write you an email because i decided that Github issue queue might be an inappropriate place to start a speculative discussion. But as i completed the email, i managed to structure my thoughts properly and come up with a concrete suggestion. So i'm posting it here. Also, Github Issues open the discussion to the public and let us format code nicely.

So please consider this to be a concept that is subject to discussion.

The format of the message remained email-like. It is very lengthy but i hope it will let you understand my idea better.

---

I've been thinking over KSS, middleman-kss and why and how i'm using them. After careful consideration, i formulated my use case as the following.

I'm a frontend developer. My work is producing HTML, CSS and client-side JS, but quite often my client does not integrate me into his development workflow. Instead of working inside a backend's codebase, i'm required to produce a separate static prototype. So i use Middleman to produce the prototype, so that i can show my client and the client can then pass it to his backend devs.

When i work with PSD templates from designer, i grumble a lot at them being a burden to work with. I believe that when a backend dev works with my prototype, he also grumbles for the same reason. So the reason why i drew my attention to KSS is my desire to make it easier for backend devs to integrate my frontend into their backend.

So there are two aspects of middleman-kss' approach that i'm concerned with.

1. Documentation is stored in two places: CSS and styleblocks. It is absolutely understandable why you introduced styleblocks: their HTML should be treated in two ways (as HTML and as plain text) and also styleblocks are now parseable templates.

   But when i write my KSS documentation (actually, i haven't written any yet, i'm only considering it), i dream of documenting HTML structure in one place with CSS documentation.

2. When i design my modules' code, i try not to impose certain HTML structure. E. g. i do .mainMenu-list .mainMenu-listItem rather than ul.mainMenu > li. This lets a backend developer turn any HTML structure into a module just by adding semantic classes to it, rather than completely rewrite it to match a rigid, imposed structure.

   The problem with middleman-kss here is that HTML code demonstrated in the styleguide does not let a backend developer see which classes and hierarchical relations are required and which are free to be modified.

So instead of showing this:

<nav class="mainMenu expandable">
  <div class="mainMenu-title">
    Навигация
  </div>
  <ul class="mainMenu-list">
    <li class="mainMenu-item mainMenu-item--current">
      <span class="mainMenu-name">Главная</span>
    </li>
    <li class="mainMenu-item">
      <a class="mainMenu-name" href="#">Проекты</a>
    </li>
    <li class="mainMenu-item">
      <a class="mainMenu-name" href="#">Решения</a>
    </li>
    <li class="mainMenu-item">
      <a class="mainMenu-name" href="#">Услуги</a>
    </li>
    <li class="mainMenu-item">
      <a class="mainMenu-name" href="#">Клиенты</a>
    </li>
    <li class="mainMenu-item">
      <a class="mainMenu-name" href="company/">Компания</a>
    </li>
  </ul>
</nav>

I'd rather show a Haml-like structure reduced to only relevant parts:

.mainMenu.expandable
  .mainMenu-title Навигация
  .mainMenu-list
    .mainMenu-item.mainMenu-item--current
      .mainMenu-name Главная
    .mainMenu-item
      %a.mainMenu-name Проекты
    .mainMenu-item
      %a.mainMenu-name Решения
    .mainMenu-item
      %a.mainMenu-name Услуги
    .mainMenu-item
      %a.mainMenu-name Клиенты
    .mainMenu-item
      %a.mainMenu-name Компания

Providing such an example doesn't remove a necessity in a pure-HTML example. That's because a backend developer does not always need to apply my module to an existing HTML structure. In most cases, he would prefer to simply copy-paste my pure-HTML example into his template.

So i think that a possible workaround to the described problem would be describing the Haml-like structure of the module in KSS. This will also be very helpful for other frontend developers: with an example of a structure, it will be much easier to understand CSS code of a complex module.

But this workaround forces you into documenting your HTML structure twice: once in KSS and once in styleblocks.

So i was thinking of a hypothetical approach of migrating styleblocks into KSS. This will let us keep all documentation in one place rather than spread it between KSS and styleblocks.

This path has two difficulties:

• it will require hacky approach to extract a styleblock from KSS and then parse it;
• it will require extending the KSS standard and maybe forking the KSS gem (with a possibility of merging it back later), because a styleblock should be programmatically distinguishable from the textual description.

As for the problem of demonstrating both Haml and HTML, i believe it can be achieved programmatically with relatively little effort.

Andrey 'lolmaus' Mikhaylov

[Darep]

This is actually a feature request I initially received from my co-workers some 6 months ago :)

Before I started working on middleman-kss, a co-worker used kss-node which added this kind of feature. It's simple and uses plain HTML, but still, you can write the styleblock straight into CSS. And it is what KSS/middleman-kss users have requested also.

The difficulties here are just as you mentioned: it's hacky, doesn't go with the current KSS standard and finding the right way to type the markup that would suit everyone is going to be a long road :)

But nevertheless, I agree with you pretty much 100% and would love to implement this in one way or another!

PS. Did you write the post on using px instead of em with media queries in CSS? Loved it :+1:

[lolmaus]

Is the post already published somewhere? I've only shared a draft via gist.github.com.

[Darep]

Brad Frost shared the draft on twitter :) https://twitter.com/brad_frost/status/400620372196093952

[lolmaus]

Oh! So much feedback!

I tried doing something like kss.inspect and noticed that the KSS gem actually extracts ALL comments, it's just the fact that nodes without Styleguide 2.1.3. aren't normally accessible via gem's methods.

So i think that KSS is smart neither in syntax standard nor in implementation. I suggest that we discuss an alternative.

The problem is that i'm being involved in a Node-based project, so i'll have no real-life playground to try Ruby stuff.

[zemd]

There is discussion already https://github.com/kneath/kss/issues/37 and I think kneath is right about code separation. I think there should be something like "pre" tag in description section to provide more details, but main code should be separated.

[lolmaus]

Sorting out my emails...

The matter is that a CSS/Sass file may describe a very complex page module ("block" in BEM or "component" in SUCKS). The styles are inevitable dependent on certain HTML structure.

This structure can be very versatile, but certain hierarchy (e. g. a list item should be within a list container) and elements (e. g. a list item is expected to be a <li>) is expected.

I believe that this should be documented in KSS. HTML is not a good way to document arbitrary structures, so i suggest using HAML or Slim.

[zemd]

one of the BEM's main concept is not to depend on certain html structure. you have enough abstractions to produce markup - block, element, modifier - there is no html tag in this concept.

each element also can be independent block, so you can describe it as regular class with it's own modifiers. there is no need to have dependencies with jade, haml etc.

---

на сколько я понял ты русскоязычный, поэтому продублирую по-русски, т.к. мой английский может быть не понятен.

одна из главных концепий бэма как раз и заключается в том чтобы не зависеть от html структуры. в методологии достаточно абстракций для этого - блок, элемент, модификатор. и там совершенно нет понятия html тэг. в bem-tools вообще свои абстракции над html - bemhtml, bemjson

каждый элемент может быть независимым и можно описать его отдельно со своими модификаторами. нет необходимости в добавлении новых зависимостей таких как haml, jade и других.

[lolmaus]

Yes, BEM elements should be as much independent as possible (in my personal projects i even do not distinguish between BEM blocks and BEM elements because of the fact of their independency).

But middleman-kss's styleblocks (which are used to document BEM blocks) do require certain structure to be rendered correctly. If you assemble your block with a different hierarchy of elements, it will be totally fcuked up. You might end up with table-rows inside table-cells, etc.

@hunterman If you find my English understandable, let's stick to English. I do understand you fine.