[thelist] Static application mockup

Lee Kowalkowski lee.kowalkowski at googlemail.com
Mon Oct 17 05:35:19 CDT 2011

On 15/10/2011, Renoir Boulanger <renoirb at gmail.com> wrote:
> I am wondering if any of you have some experience with creating reusable
> HTMl/CSS patterns
> I am working along with a team of 7 programmers and I have to provide them
> all html blocks so they can concentrate on the logic.
> So the idea is simple and here's how I do it. I'd like your opinion:
> My question:
> I'd like your suggestions about:
> 1. Form generation on the framework side configuration that then follow
> markup conventions
> 2. Partials (or whatever name) to generate repeatable chunks of html
> 3. General workflow you use
> I cant wait to have your suggestions
> Cheers

Hi Renoir,

I maintain the corporate CSS for a large UK government client.  There
are at least 100 developers across several departments using this CSS,
and at least 50 web applications used internally and externally, all
referencing the same set of CSS files.

As you have recognised, you can't expect all those developers to be
familiar with the corporate brand, let alone HTML & CSS, especially
when engaging temporary staff or third party suppliers, they need
something to demonstrate the prescribed HTML required to achieve the
corporate brand, after all, CSS is not magic.

Our main developer reference is a single HTML file that documents and
demonstrates all the GUI components (approx 75 across 20 categories)
supported by the corporate CSS.

All the components are on a single page because this makes it very
easy to test across multiple browsers (e.g. just make a modification
and press refresh, nothing to navigate).  It also makes the entire
reference easy to review.

Each component has documentation above it, no hovering is required.
This can be switched off with a script which physically removes the
documentation from the DOM so the layout of the components can be
reviewed in a realistic setting.

Embedded into the documentation for each component is a "view source"
link which will reveal a PRE block with the actual source code that
was rendered (not a copy).  The source code is fetched using
XMLHttpRequest when the page loads and the HTML is formatted in such a
way to enable extraction of the rendered component's source code
without jeopardising layout (i.e. white-space only, no containers or
comments are used to identify the HTML to display as the source for
the component, because they can interfere with the rendering of the
component - comments might be OK these days but IE6 had a ghost-text
bug and HTML comments did not help).

There is a statically-positioned table-of-contents at the right of
this page, so the developer can expand a category and jump to a
components without having to scroll to find them.  This also generated
from the components as they are discovered in the HTML, so
zero-maintenance is required here too.

In development we have custom framework that reads and caches the
prescribed HTML from files for use in the pages for the components.
The idea here is that if we need to change the HTML for a component
(e.g. perhaps to add ARIA support), we can do so without having to
recompile and redeploy our applications (there are just too many and
that would be expensive).  There are many unit tests to ensure the
framework components produce the prescribed HTML.

If anybody raises a defect against the CSS, they have to provide the
HTML and a screenshot.  80% of the time, the developer got their HTML
wrong, and the defect is resolved purely by giving guidance.  When
fixing the CSS, the reference manual is updated first to demonstrate
the defect, before jumping in and fixing the defect.

The reference manual has section numbers and the CSS is
structured/grouped according to the sections to make it easy to find
the CSS rules for a particular component.  All the base rules are at
the start of the CSS file.  The main CSS file is just over 2000 lines.
 I'm not using any special tools to author the CSS, just a text

It's difficult to find any good examples of this kind of document on
the web, I've seen this kind of thing referred to as "Style Guides" in
the past, but searching for "CSS Style Guide" mostly results in pages
containing CSS coding standards, rather than a corporate brand/website
reference manual.  Googling around there seems to be very little
emphasis on suggested practice for documenting CSS and communicating
prescribed HTML for large teams, but I did just find this:
which is a fine example of the kind of thing I've been going on about!


More information about the thelist mailing list