(Living) Styleguide Centered Front-end Development

Living-Styleguide-Centered-Front-end-Development.md

(Living) Styleguide Centered Front-end Development

Based on / Using:

• BEM (OOCSS needed because 'components')
• SCSS
• NodeJS(?) ([or generate] static)

Gobal flow

1. Set up global project FE Structure (ITCSS/SMACSS/etc)
2. Build/change (new) component
3. Generate new SG
4. Test / compare (screenshots/linting/etc.)

1: Global FE structure

We'd need a highly modular structure for this to work. BEM/ITCSS/SMACSS etc. Also: we'd need to make sure we write our CSS properly and work OOCSS.

2: Build/change (new) component

A 'component' contains: HTML, DATA, CSS and optionally JS.

There should be one(!) 'canonical' variant of something. Using 'production' CSS/JS and HTML.

• Create components/my-component/my-component.html template (e.g. handlebars/etc)
• Create components/my-component/my-component.json with content (data)
• Create components/my-component/my-component.scss with DSS-Like meta-comments /* @html: my-component.html */ etc.
• Create components/my-component/my-component.js (e.g. browserified module)

The above could possibly be generated by a script: npm create-component my-component. (The component could be @imported automatically in e.g. main.scss)

If you go really modular, you could create a seperate 'package'(.json) for each component. With its own package.json and tests etc.

3: Generate new SG

Generating a Styleguide should do the following:

• Loop over all components in components/

• (re)Generate new 'production' CSS from SCSS -- Lint/Hint -- Minify -- etc -- Break on Linting/Syntax errors -- Output to styleguide/my-component/

• (optionally) re-generate my-component.js -- Lint/Hint -- Minify -- etc -- Break on Linting/Syntax errors -- Output to styleguide/my-component/

• Compile my-component.html from template + data -- Minify -- etc -- Output to styleguide/my-component/index.html

This compiled styleguide/my-component/index.html should be stand-alone.

• Linkable

• Create screenshot(s) styleguide/my-component/my-component-xyz.png of styleguide/my-component/index.html

• re-compile complete styleguide HTML in e.g. ./styleguide/* -- Add/import new component HTML to SG files

etc. etc,

Awesome document. At Mirabeau we're actively trying to live this philosophy, and we wrote some tools to help us achieve it. The used conventions and tools differ, but the 'code your styleguide' idea might be the same.

Have you seen https://github.com/branneman/frntndr/? We're re-implementing this at the moment here: https://github.com/mirabeau-nl/frontend-bootstrap - They're very basic, but they're a first step :)

Thanks @branneman! Everybody seems to be doing the same thing huh… ;-)
I guess that's a good thing: I already learned something from how you've set up your gulp tasks at Mirabeau 😉

The Gist above simply was a braindump for how I'd like to approach 'Styleguide-First' development. I am currently struggling with what would be a most flexible, DRY and robust way.

I'd like to be depending on as few tools as possible. For that reason I'm not so happy with most styleguide 'systems' out there. Also: I'd like to move away from Gulp and use NPM Scripts directly.

Would love to hear your thoughts on this. Thx