Re-organise pattern library

[james-nash]

Is your feature request related to a problem? Please describe. Currently, the way patterns are organised in our online pattern library is a bot messy:

• Atoms is a mix of plain HTML elements (mainly for the purpose of visualising the base styles Gravity applies to them) and specialised components (with a class on their root element and/or a prescribed composition of HTML elements)
• The division between molecules and organisms is unclear
• Patterns with multiple states (e.g. plain button, disabled button and submit button are all the saem HTML element) or variants are listed as individual entries causing the false impression that they are separate components
• Sub-categories are not always used consistently (e.g. some templates and pages are top-level, others are not)

This causes a number of issues:

• It's not always clear where to find or add things. For example there are various kinds of lists scattered across atoms, molecules and organisms
• There's no good "home" for object and utility classes

Describe the solution you'd like We should:

• establish some clearer guidelines for organising our patterns (possibly adding to or changing the categories we have today)
• document those, and then..
• reorganise the patterns accordingly

Additional context This came out of a chat with @dw-buildit today, while trying to decide where best to put a .grav-o-two-column class. Layout primitives like that don't fit well under atoms since they layout a set of other things, so they are inevitably applied to some kind of container. And yet, it's mot clear if they should be considered molecules or organisms, since we don't (and can't) know how complex the things being laid out will be.

I'd argue utility classes have similar challenges. Really, objects and utilities are not components at all, so perhaps they should exist outsode of the Atomic Design categories.

Dan also, rightly IMHO, pointed out that our "atoms" section is confusing. It is a combination of plain HTML elements (some of which have or imply some kind of composition - e.g. <table> or <ul> - and thus don't really feel like indivisible atoms) and Gravity-specific components like "nav link" or "pull quote". What we both felt might be a good solution is to divide them. "Atoms" could be reserved for the Gravity specific things only and plain HTML elements go somewhere else.

Reviewing older issues, I see that @ThePeach suggested more or less the same a year ago in #106.

[james-nash]

Patterns with multiple states (e.g. plain button, disabled button and submit button are all the saem HTML element) or variants are listed as individual entries causing the false impression that they are separate components

This point will be easy to address once we migrate to Fractal (see issue #264 / PR #262), since we can give such components a custom preview template that shows all possible states. Alternatively we can do them as "variants" with a collated preview.

[james-nash]

I've given it a bit of thought, and here's my proposal for an updated structure:

├── Particles (design tokens & assets) - same as now
│   ├── Color
│   ├── Typography
│   └── ...
├── Elements (just the plain HTML elements)
│   ├── Inline-text
│   ├── Block-text
│   └── ...
├── Helpers (object & utility classes from our ITCSS structure)
│   ├── Layouts
│   │   ├── Multi-column
│   │   ├── Page
│   │   └── ...
│   ├── Utilities
│   └── ...
├── Components (components from our ITCSS structure)
│   ├── Atoms
│   ├── Molecules
│   └── Organisms
└── Examples
    ├── Templates
    └── Pages

Introducing a new top-level and the dividing existing stuff into it aims to address a number of issues we currently have:

• Separating "elements" and "components" avoids the confusing jumble of plain HTML elements and more opinioned/specialied components that are unique to Gravity.
  • Elements are just the plain HTML elements. So, we no longer need to scratch our heads about whether a <ul> or <table> is really an atom or not. They now stand apart from the Atomic Design categories. This also makes the pattern library's navigation align with our SASS source code folders - this now maps directly to the elements layer in ITCSS.
  • Components then are things we've created ourselves. In most cases these will each have a grav-c-* class. I think we can continue using Atomic Design (up to organisms) as the 2nd level within this. I suspect classifying this will become easier too.
  • This separation might also be useful for when we start publishing our Nunjucks templates (or if someone wanted to make a React library or similar). I think the "components" section is exactly what we should be publishing. Creating shared templats for HTML elements is a bit redundant. Likewise, templates and pages are really just for showcasing possible uses of the components. It's the components themselves that are useful to downstream consumers. (I realise we'll need to disentangle our element Nunjucks templates from the component ones to achieve this, but it'd be worth it IMHO)
• In a similar vein, object and utility classes were always an awkward fit within the Atomic Design categories. Is a 2 column layout an atom or molecule? I'm now suggesting it's neither - these things should live in their own category.
  • I've called it "Helpers" for now, but I'm not totally sold on that name. I didn't want to call it "Objects" (like the ITCSS layer) since I think that name is likely to be misunderstood by people not familiar with ITCSS or OOCSS. Furthermore, I foresee at least some utility classes falling under this category (others, like color schemes and font sizes, probably feel more at home under particles - just like we have already today). Utilities for modifying paddings or margins don't really fit under particles though and may be more at home here. Perhaps "Layouts" would be a good name for this section - unless we can think of non-layout-related things that might live here too.
• Splitting out templates and pages into an "Examples" section will hopefully mak their purpose clearer too.
  • We've historically abused them as a crude way of prototyping the Buildit website. At times this has confused newcomers who mistakenly thought making a "page" in Pattern Lab would get it into the website and were then surprised to find they had to re-make it in the website's code. Hopefully clearly marking them as "examples" will help avoid extra work and/or disappointment in future.
  • As a consequence of the above, we've also ended up with some gnarly templates like the section one (see issue #276).

Overall, I think something like this structure would be big improvement over what we currently have. It'll be quite easy to implement in Fractal too, since that lets us have as many levels of navigation as we want.

There'll be a few items that might feel a tad odd. For instance buttons will come under elements and not components - people familair with other design systems might find that a bit unintuitive. But, I think people actually using or working on Gravity will quickly get used to that. Besides, it's certainly no worse than it is today. :-)

[james-nash]

Given the lack of objections and counter-proposals, I'll make a start at implementing my proposed re-org in a PR. It'll probably take a while, so please be patient. Will report progress back here once there's something to see...