Pattern Lab Thoughts

pattern-lab.md

I love PL and the work that Dave and Brad have been doing. This is just random bullshit I've been thinking after a week of Pattern Lab use. Just

1. Just a source directory?

I've found that working on my current Pattern Lab, the only directory I really need is the source directory. That makes me think that all the config|core|extras|etc folders could not exist or be hidden from the user. That way a generic Node process that could be used by grunt, gulp, broccoli, etc might be beneficial. The "engine" is hidden from the user. Then updates could be seamlessly injected where now it'd be a bit of a manual process.

I think the simplicity of just having the files you're working on decoupled from the technology would be great for onboarding new users. Edit your source files (now at the project root) and point a nodeapp/grunt/gulp task at it.

It feels like a question of do you want it to be WordPress for patterns (engine coupled) or a Jekyll for patterns (engine decoupled/hidden).

Relevant links:

• PatternLab Jekyll

2. YAML/JSON instead of Ordinal Folders?

I've wondered if it's easier to just update some JSON instead of keeping folder and file names numerically prefixed. If you delete a pattern, it's a bit of work to re-ordinate all the other files (lots of git changes, etc).

This would maybe help in up-cycling patterns into a larger system (which is a lot of people's dream). I can then tell a backend developer to include() the molecules/global/pagination.mustache instead of molecules/02-global/03-pagination.mustache/, where the numbers seem subject to change. PL could then start existing within a directory of a larger system.

3. Extensions?

I talked with Brad about this, I know it's on the roadmap. I wonder if Jekyll's _plugins structure might be good here, and those are little web components (HTML/CSS/JS ... Polymer?) that inject features in to the style guide header. Extensions could be included/excluded using YAML/JSON as well.

I just wanted to +1 all of the above. Thanks for throwing together these notes, sir <3

I've found that working on my current Pattern Lab, the only directory I really need is the source directory. That way a generic Node process that could be used by grunt, gulp, broccoli, etc might be beneficial. The "engine" is hidden from the user. Then updates could be seamlessly injected where now it'd be a bit of a manual process.

This is probably the number one challenge we've run into.

Some other random bits:

I'd love to see a cleaner way of integrating PL (especially the Node port) into existing projects where I can just rely on it as a dependency and set it up to build the PL off a source directory which can be reused for styles in the rest of my project. It should be trivial to choose whatever build system you want and easily get your PL lab built without as much coupling to Grunt and the current setup.

I've seen some folks talk about introducing Jekyll and Assemble into the picture for the build portion. I think this is cool, but do think we should keep in mind how many additional dependencies this might introduce into the picture. The way I see myself (and my users) using PL is as part of an existing project where you have a patterns directory with your built PL stuff and otherwise just use your styles source per usual. That might just be me however :)

@davatron5000, @addyosmani,
Thanks so much for putting these thoughts together.

1. It took me a while to see what you're getting at here, but basically you're talking about having PL function similar to Jekyll, Sass, and all those other command-line-driven tools? Philosophically, Pattern Lab is as agnostic as humanly possible, so I'm pretty sure I agree with you both that whatever can be done to further hide the engine, that would make sense.

The only thing I'm scratching my head about is the source only part. Jekyll still needs compiled, and those compiled files are moved to a destination folder. I would anticipate Pattern Lab would still need some semblance of a public folder, even if it were to live under the root source folder.

1. I'll admit that the numbering system is a bit clumsy, and it's mostly there because it's left over from my original version (which had no Mustache, no configs, no nothin'). I still like the numbering system because it works, and people can wrap their heads around it. Another philosophy of Pattern Lab is to be straightforward, so that's why I like this approach. That being said, having a JSON config would be a nice enhancement. It's certainly a lot cleaner, and can help with a lot of workflow issues. @dmolsen, is that relatively easy to implement?
2. Thanks for the Jekyll example. I know that @dmolsen has been thinking about the best way to structure plugins.

I'd love to see a cleaner way of integrating PL (especially the Node port) into existing projects where I can just rely on it as a dependency and set it up to build the PL off a source directory which can be reused for styles in the rest of my project.

I'm not sure I follow you here. Any way you can give an example of what you're looking for?

The way I see myself (and my users) using PL is as part of an existing project where you have a patterns directory with your built PL stuff and otherwise just use your styles source per usual.

I've seen/heard a lot of different use cases for how Pattern Lab is being used. Here's some of them:

• As a tool to build a project from scratch, generating production-ready front-end code to be later integrated into a CMS (this is how I've been using it since its inception)
• As a tool to manage an existing design's patterns (sounds like what you're describing)
• As a quick way to prototype interfaces, creating scratch code or even just stitching together static images (which I think is super clever)

At the end of the day, it sounds like we all want Pattern Lab to be clean, agnostic, and portable. That's definitely been our mindset from the outset, so this feedback is invaluable. Thanks!

@davatron5000 / @addyosmani, awesome, I'll try to restate some of these in my own words so you can tell me if I'm getting them right and we can discuss. then if you think it's worthwhile I should be able to put a POC together pretty quickly. (I do want to mention up front though that I'll be doing the POC with Assemble. But that doesn't mean we can't just use the result as a way to getting dialog going so that we can find some interesting solutions to these common problems. so I have no expectations, if assemble isn't what you need, that's okay):

Do these recaps sound right?

• generic node lib that can be used with any toolchain, grunt/gulp/broccoli etc.
• decouple the templates from the build system
• allow the use conventions and organizational patterns that make templates modular and reusable across projects.
• have the ability to augment the "core" build system with technology that enables you to use your own conventions.
• plugins/extensions should be easily registered

---

also:

• is the goal to implement something specific to PL? or is the goal more general? Clarification here would be good since PL is both a set of conventions and a build system that is specific to those conventions (also, see https://github.com/assemble/assemble-pattern-lab/blob/master/templates/_helpers/patterns.js for an example of how handlebars helpers can be used to build any PL patterns)
• would the HTML templates mostly consist of lorem ipsum content? I think we want them to be more templatized, but we should probably get a little more specific. Actually I guess a better question is what your expectations are about how components can be used together. This all comes down to the template engine and how context is managed. Some template engines are super fast, some focus on ease-of-use, others are more extensible, and some are really good at context etc. I think this will be the most important thing to consider, because your expectations of how templates can be used together will determine how much flexibility you have with the templates, how reusable they will ultimately be across projects, and (to @addyosmani's point) the dependencies required. Whichever way we go, there are trade-offs to be considered. but we can discuss if there is an interest.

ha, sorry I just saw @bradfrost's reply, haven't read yet but I posted my reply before I saw it.

Okay, having read through Brad's comments, I guess I'll wait to see if PL is the specific focus.

I think PL currently works the way @bradfrost intended. You can use it to start a project and develop front-end resources.

Personally, I haven't used PL on a project for a couple of reasons:

• it's very opinionated (intentionally so, I do understand that). You have to "buy in" to the entire PL concept and structure to use it at all.
• PHP Dep. I know, it's on every machine and every server. I just don't feel comfortable with it.
• It's complex. It creates solutions I don't want for problems I don't have. i.e.:
  • asset management
  • autoreload
  • dev server
  • viewport resizing

I understand the value in having a tool that you can just open up and start developing, but some people have tools and processes that work for them, and PL is currently unusable in those cases. I'm pretty sure the original intent of pattern lab was to provide a tool you could use to create a design system - something it does really well. I think it's time to mature our tools and push them toward a more unix-y "do one thing really well" approach.

@VinSpee,
I hear you that Pattern Lab does a lot, but I'm not sure if you know that almost everything about Pattern Lab can be configured. Don't want to use "atoms, molecules, organisms"; any name can easily be changed. Don't need auto-reload, viewport tools, etc? They can be switched off in the config. Just want to use Pattern Lab to build the patterns and nothing more? It's a simple command.

It's been a process to make Pattern Lab simultaneously flexible and robust, and we're taking further steps to make it as modular as possible. Ultimately, what we're really shooting for is total modularity, where any feature that isn't the builder itself becomes a plugin.

As for the PHP dependency, I'm personally not that miffed by it. But from the sounds of this thread, there appears to be a lot of interest in making it node and more agnostic in general. Which is awesome.

@jonschlinkert,
I think there are definitely some common issues that would be great to coordinate on, regardless of whether people are using Pattern Lab, Assemble, or something else altogether. There's a lot of opportunity for tools like this, and I think ultimately we're all on the same page that the philosophy/workflow matters than the specific technology used to execute it.

A bit to unpack here but I wanted to offer my two cents…

1. Just a Source Directory

I think we're just going to have to accept that there's a fundamental difference to how (I feel) the PHP world handles system-wide installs vs. node/Ruby. I think the examples given, Wordpress vs Jekyll, really highlight this. We shouldn't be saying PL works this one way across platforms but, rather, it should default to some sort of "best practice" for a language. If it's gem install patternlab and then you just have the commands? Two thumbs up. Same with node. If the node version should follow some other best practice and leverage the strengths of that platform we should do it. We (and the maintainer, Brian) do accept PRs ;)

Frankly, that sounds to me like it's small potatoes on the vast list of questions that fall out of the larger question, "How do we think of maintaining a cohesive (not necessarily identical) project across platforms?"

2. YAML/JSON instead of Ordinal Folders?

Ordinal folder/patterns are not required to use Pattern Lab. At least the PHP version will work without them. The file system acts as the database for the nav so… if you want things to come in a certain order (e.g. templates before pages) you have to go for the numbers. As Brad noted, he matched it up to his previous version. But it can be dropped whenever. JSON sounds… indirect but it's possible to generate a JSON site map that gets hand-edited into the order one might want. Just have to make sure to keep existing orders during each build of the JSON to add new patterns.

And I can see you haven't seen pattern states (yellow dots on the home page template are a good example) and pseudo-patterns (primarily used for offering varied versions of a template/page) as they introduce more work on the file system.

3. Extensions?

Extensions/plug-ins are something that I've had rattling around in my head for a while. I just haven't spent on a ton of time on figuring it all out. Brad would say pattern states are a good candidate for a plug-in but I see that crossing so many parts of a system… it's tough to figure out how to deliver all of that and how to install it. I'm happy to follow the direction of someone else. And we can definitely split extensions between pure front-end and something more complicated like pattern states. Tackle one problem at a time. The QR code feature is a good one to use a test of modularizing the front-end specifically.

Actually, I'm shortly going to work in KSS support and maybe that's a good time to step back and think about how to do it in "plug-in" fashion since it, like pattern states, will touch on everything and only a subset of people will want to use it.I finally just did that for back-end engine support to allow patterns to be written in Twig.

4. Developing a Spec

What wasn't asked but seems to be an undercurrent to all of this is… what is Pattern Lab's (in general) spec? What qualifies as being Pattern Lab-compatible? Especially when it comes to being cross-platform and following a platforms best practices/norms? Right now it seems like there's a few… assumptions about how PL works based on docs, looking at the demo, and maybe some implementation aspects inherent in the current node version. I've really dropped the ball on a) developing a real spec and b) communicating changes to a spec. Brian has been left to pick apart and play catch-up on the PHP version. That isn't easy.

I'll take some time after I get back from holiday and write out what needs to go in and what needs to come out to be at the current version of PL. From there we can pick apart what's nice to have and what's necessary for delivering the core of PL (or a modular pattern builder thingie). That is developing and re-using patterns layered within the "viewer" for team and client review. We can then review where that leaves the node version and what we need to do to best push that forward to meet "node best practices" and the spec.

Thanks everyone for the input and feedback.

Hi all. I super-duper appreciate the thoughts above. I myself have struggled with how best to use PL - and have found success with a number of the use-cases Brad mentioned, as well as showcasing it as a more modern workflow over static PSD throw-over-the-wall-syndrome.

PL-node has always been feature-poor compared to the PHP version. I contemplated naming it patternlab-grunt, as some have indicated it could be considered an unnecessary dependency. Some decisions need to be made, however, while finding balance between approachability (see here) and cutting with the grain of current front end dev practices. The same thought was given to shipped preprocessor support if I recall.

That said, I really welcome the larger conversation, am excited to see what @dmolsen and @bradfrost consider the PL Spec, and really do welcome PRs! There is certainly a lot of ground to make up, and some basic maturity issues that need sorting out :)

Short term PL-node roadmap:

1. dependency, grunt and npm cleanup
2. documentation improvements, including contribution guidelines
3. datamodel refactoring, more dry, test-driven

Thanks!

while finding balance between approachability (see here) and cutting with the grain of current front end dev practices.

Well said, @bmuenzenmeyer. This balance is something that @dmolsen and I have taken very seriously right out of the gate. There is certainly the potential to make a really robust Pattern Lab that relies upon relatively advanced tools. But in doing that, you end up giving up that approachability to a whole lot of folks. Kudos to @dmolsen has done such a good job at keeping the dependencies to a minimum (it only requires PHP, nothing else).

What I would love to try to solve is a way to create as robust a system as humanly possible while still being approachable to folks who aren't fluent in Bower, Grunt, and the like. I enjoy playing the part of the idiot, largely because I am one :) So the goal is to create a tool that's simultaneously advanced yet approachable to beginners. I like that challenge.

IMHO PL is the patterns, not a build system (or shouldn't be), when there are much better existing alternatives that can accomplish what you need. So if the goal is to help PL become a better build system, I'm happy to give feedback if it's desired. But there probably isn't much more I can offer.

Every single thing that has been listed on this gist can be done by Assemble out of the box. Just as PL is about the patterns, Assemble is focused on being able to build components into any pattern you need. If you want to build PL with Assemble, just use the PL helpers. If you want to build YUI docs, use a YUI plugin, if you want to build OOCSS, use a plugin, and so on.

Shifting gears, on the topic of deps, IMO keeping dependencies to a minimum isn't a goal unto itself, it needs to be balanced with what needs to be accomplished. Just as developer convenience is more important than micro-performance, shaving off a couple of dependencies at the cost of losing access to context in deeply nested components would be a bad trade-off. I guess my point is that deps shouldn't even be a part of this discussion. Not until the goal is reached, then we can look for ways to optimize. just my 2c

Hi Guys! I'm just building a styleguide system similar to pattern lab.

TL;DR:
Everything is a remix. Pattern Lab was almost exactly what I needed, and what the OP is asking for is just what I built over the last few weeks - without knowing about PL when I started. Seems like we all share the same mindset and ideas...

The aims I had in mind was to recreate the structure of a "classical" styleguide without its drawbacks and with maximizing the benefits of real code, so:

• address the needs of the client, template devs and designers
• document how things work in real-life - with interaction => for the client
• document how to build HTML so it uses existing modular styles => devs working with templates
• document what building blocks are already there and how they work together, to enforce consistency of the design and help => designers
• make the whole thing really easy to maintain for us frontend devs
• and: use it as a build-tool for frontend development (like Grunt/Gulp, with things like browserify, less, sass, icon font generating etc. easily added)

Trying to build a living styleguide, I first stumpled across StyleDocco, KSS, Sassdown and the likes. Easily integrated into Grunt/Gulp, but the output was too technical to recreate the structure of a "classical" styleguide. Also, it documents the CSS rather than how to build the HTML.

So I started thinking about a usable structure. I still didn't know about Pattern Lab then:

• have a folder structure which will represent the styleguide navigation (like PL)
• organize the order of items - with TOC files or via file name prefixes (also like PL)
• provide a way to test patterns in different viewports for responsive design (hello again, PL)
• have the documentation right along with the pattern (buttons.html + buttons.md) to document the usage (like @davatron5000 suggests)
• optionally: modify single patterns with custom CSS for creating styleguide-only things (like color swatches, grid mixin documentation, font listings etc.) => I use an Iframe for each pattern to encapsulate the CSS (like StyleDocco et al)

So: each pattern consists at least of an HTML sample rendering, HTML source, and optionally usage documentation as markdown text and/or CSS.

I built the whole thing based on gulp-webapp and implemented all of the things. THEN I stumbled across Pattern Lab! Whoa! Someone did it before! And it's the brainchild of Brad Frost :) - how could I miss that!? Atomic Design FTW! The PL concept is basically the same. I just didn't think of nesting patterns inside of each other. So I added that. But there were things I missed in Pattern Lab - basically things the OP thinks about:

• the documentation is too separated in JSON files
• no frontend build tooling
• some essential design differences

Now: should I contribute to Pattern Lab? Yeah, basically I should. But it's not that easy: I'm a PHP analphabet. So: patternlab-node? Hm, the PL structure is too different and my attempt already had reached a similar progress. Fork it and bend it to a whole new direction? It would be too different, so I continued my thing.

Now that I see that our needs and ideas are so similar, I will open-source my work and see how we could make one big thing out of it!

Thanks @bradfrost, @dmolsen and @bmuenzenmeyer for your inspiring work! In the end I copied a lot from you - well, you got it just right in so many points!

Sorry for the long post, I just couldn't resist.

Cheers!

Here it is: https://github.com/levito/living-styleguide

I'd love to hear your feedback!