Documenting CSS architecture

I’m the lead front-end developer on a 9000 page website, we’re currently looking to refactor our CSS along the lines of SMACSS/BEM in order to make it more maintainable/reusable.

I’ve read the SMACSS guide book, watched various OOCSS and BEM presentations on youtube and I understand the concepts, however the particular implementation of the principle will vary from site to site - we have 3 front-end developers here, and also changes tend to stick - by which I mean 5 or 10 years later you are working with the consequences of your (or someones) decisions - so I would like to be able to clearly document how we designed the CSS architecture in the same way that we might document how we wrote our web apps.

Has anyone any experience of developing a large modular reusable CSS architecture for a big site that has a team of developers on? What kind of documentation is useful? Is there a kind of diagram to show the relationships between HTML and CSS ?



a good answer to this is 44 minutes into this video : ‘CSS for grown ups’

Interesting section thanks and hope it answered your question.

Sorry I couldn’t add anything useful to the discussion as documenting CSS is not something I have had to do ( apart from reference books) as I mostly work on small sites that don’t really need that sort of documentation. For large sites though with a team to take care of then the method mentioned in the video looks like a useful strategy to follow (although quite a bit of work).

I googled around and found this page:

and reading through that found this page
I think this is a good approach, show visual examples, have code examples alongside, so built this
it’s a work in progress and there are problems with it, but its a central repository for style information that all our front-end dev staff have access to…

Thanks James for following up with your findings. :slight_smile:

I will be interested to see what approach you finally take and how it works out for you. I’m sure this will be of interest to others on the same path.

From my own perspective it seems a lot of work as I code mainly PSD to html templates for clients and can do as many as 5 different templates a week so there’s no way I could incorporate any style guides into the work I usually do. However I have worked on a few large projects over the years and I could see how a style guide would be useful to all concerned.

I used to work on one off projects for clients, often using drupal or wordpress, but for the last 3 years I’ve worked solidly on one website, like I mentioned it has 9000 pages, 6 front-end developers and about 200 content editors, after 3 years working on the same constantly evolving and growing website I think you begin to see different aspects/problems - the maintainability of CSS being one, how to work in a team with members joining a leaving being another. I don’t think I would have really got the point of a CSS architecture if I hadn’t had this experience.

I’m not trying to be rude or something, but how does “9000 pages” factors in with “more, much more CSS to maintain”?
From the horse’s ( mouth: “What I’ve found is a process that works equally well for sites small and large.”

well it shouldn’t - however I think a small site done badly is much easier to fix, whereas a large site done badly is much more difficult to fix - if it was 9000 similar pages (i.e. used same content type / layout) then it wouldn’t matter one bit - but the situation we have is that site editors are uploading content and combining templates in ways that are hard to predict - and if you make changes to the CSS unlike a 50 page website it’s a collosal time consuming job to check the visual impact accross 9000 pages, it’s going to take half a day and be a pretty unpleasant job.

It’s not just a matter of 9000 pages, that’s just an indicator of scale, just more of a combinatory problem, more content, more templates, more editors, more devs, more designers.

Smaccs works as well for small as well as large sites, it’s just that smacss etc. is a guideline for architecting the CSS it doesn’t do the hard work of solving the problem, and there are easier ways to do CSS, if you don’t need the CSS to be scalable and modular then why waste your time making it that way? If you’re site is small, the pages are very similar to each other, or it’s lifespan is short (i.e. unlikely to need a lot of maintenance) it might not be worth the trade-off

Organizing the CSS code is only good after you have a sound CSS code. I think you first need tools to check your CSS for redundancy and for analyzing its optimization level. Organizing can’t help with either of those, redundancy or optimization.

I disagree, I think organised CSS can help checking both for redundancy and optimisation.

Organised CSS is maintainable CSS and code maintenance is paramount to optimisation.

There are no unused selectors on the site (this is easy to test for) but this is not the end of redundancy.

‘Redundancy’ or to be more accurate ‘redundant duplication’ should be related to reusability, we will run static analysis on the entire site to check for this kind of redundancy, but this is a hard problem, because it’s not about unused selectors, but another issue of a combinatory headache (combinatory problems are a hard class of problem to solve) - for example, you could theoretically rewrite your CSS so every rule (key:value) had it’s own class - (you wouldn’t do this obviously) but then redundancy of html/selector relatonships could be easily solved, obviously this would be mad - but by using this extreme example you can see that, for example having a rule with ‘width: 75%’ in one block and ‘width: 75%’ in another suggests you could create a ‘width–three-quarts’ class (for example) but whether you should or shouldn’t do that depends on the context - the context in this case is ‘the rest of your CSS’ -> that kind of analysis for redundancy is hard and exactly what implenting along the lines of something like SMACSS would begin to solve.