Patterns: Nesting, Navigation & Taxonomy

[georgiee]

Hello Team,
I see this topic more general so I chose to create an issue here in the-spec. The current situation of having so many projects related to Pattern Lab makes it sometimes very hard to decide which place to use for giving feedback.

The problem

My current problem arises with the following situation.

From the documentation:

Deeper Nesting

Both PHP and Node versions support nesting of folders under patternSubtype.
For example, you may want to organize your pattern documentation, pattern,
Sass files and pseudo-patterns in one directory like so:

[...]

Folders can be nested under media-block/ if desired but this is discouraged
because of possible collisions when using the shorthand partial syntax.

By doing the discouraged you will be welcomed by the following message in the shell.

Warning:
A pattern file: [...] was found greater than 2 levels deep from ./source/_patterns/.
It's strongly suggested to not deviate from the following structure under _patterns/
[patternType]/[patternSubtype]/[patternName].[patternExtension]

While Pattern Lab may still function, assets may 404 and frontend links may break.
Consider yourself warned.

Understood. But we have two possible outcomes now.

1. Ignore the recommendation and use whatever depth I want:
No. It's not acceptable as I don't want any 404 errors, broken links and whatever else that could fail. I would go even further and suggest to disable the feature at the moment. You don't recommend it and it's not really working so why should I even be allowed to use it?

2. Work with the recommendation and stick to the two level structure:
I will live with two levels and decide to create a folder per atom or molecule.
Following the recommendation of [patternType]/[patternSubtype]/[patternName].[patternExtension] this will look like the following- assuming working on a single atom called "quote".

|-- atoms
    |-- quote
        |-- quote.md
        |-- quote.mustache
        |-- quote.scss
        |-- quote.other-extensions
        |-- quote-variant.md
        |-- quote-variant.mustache
        |-- quote-whatever...

Yes this works fine.

Now imagine that I want to add more atoms. Messages, Lists, Headlines, Some Fancy Labels, you name it. I add atom after atom and I'm proud of every new one and progress even faster, creating more and more atoms. Soon my navigation will look like this:

 ------------------------
| ATOMS                   |
 ------------------------
vvvvvvvvvvvvvvvvvvvvvv
 ---------
| QUOTE v |
 ---------
 ------------
| MESSAGES v |
 ------------
 ---------
| LISTS v |
 ---------
 -------------
| HEADLINES v |
 -------------
 ---------------
| FANCY LABELS v |
 ---------------
 ----------------
| RAINBOW LINKS v |
 ----------------
 -----------------------
| BLINKING BOLD WORDS v |
 -----------------------

The filesystem is fine displaying all those new atoms. The editor is awesome in finding what I want to edit. But the given two level navigation will fail making it accessible or clear what's even available. It's going to be a huge vertical mess sooner or later.

The way out is easy: We need some taxonomy. Derived from the filesystem by allowing more than two levels (like now, but not working) or by some explicit configuration to group all those patterns.

The folder structure would be the easiest to understand. But is it even technical viable at the moment or why is it in this unstable state?

Maybe a configuration file is easier and more flexible? Let's look at it.

Idea: Taxonomy Configuration

The configuration option could be a global file categories.json containing something like this:

categories: [
  {
    title: 'Text',
    patterns: [
      'quote',
      'messages',
      'lists',
      'headlines',
      'fancy-labels',
      'rainbow-links',
      'blinking-bold-words'
    ]
  },
  {
    title: 'Form Elements',
    patterns: [
      'label',
      'checkbox',
      'textarea',
      'textfield',
      'radiobutton'
    ]
  }
]

Having such a file store present we could provide even more data per atom.

,
metadata: [
  {
    pattern: 'label',
    tags: 'form, important, backend, animated, a11y',
    jira: 'ID-1234'
  }
]

This file would be more powerful than the filesystem approach:

• We are independent from the filesystem.
• We can freely arrange the patterns in the navigation.
• We don't need annoying prefixes like 01-, 03- of prefixes to maintain a correct sorting of patterns.
• We could list patterns at multiple places if we want
• We could attach tags to patterns to provide another navigation angle.
• We can name patterns independent from their ID.
• We can hide pattern in the navigation while keeping them accessible from internal linking.

We could make such a file optional. If I choose to create such a file I would take over the control of building the main navigation in very explicit manner. Maintaining such a file wouldn't be so hard. Everybody else would live with the filesystem based navigation present today.

I appreciate the convention over configuration approach Pattern Lab takes. I loved it using Ruby on Rails at that time and I love it in Pattern Lab now. But it really feels good taking the burden of building the navigation from the filesystem and put in in an explicit configuration file.

Pattern Lab is not only a living styleguide it's a documentation tool for non-developers. The navigation is therefore are very important part to make the work of the developer and designer accessible. That's why I put such an effort into composing this issue. I hope you have understood what I mean.

What do you think?

[bradfrost]

Hey @georgiee,
Thanks for these thoughts. I'm unfortunately unable to speak to the issue but maybe @bmuenzenmeyer and @dmolsen have some thoughts. Thanks again!

[bmuenzenmeyer]

Hi there. I am mobile with a sleeping baby on my chest, but I'll try my best to reply...

I understand the natural limits any navigation pattern approaches with high volumes of patterns. The current system has limits, a forked styleguidekit-assets-default nav with a side navigation has limits, and your categories json does too given a user's volume and taxonomy decisions. I think people are far too attached to the Atomic Design convention and get tunnel vision that everything needs to fit under atoms, molecules, etc, leading to high volume. There is nothing stopping you from making pattern categories of text and form like you provided.

A couple other specific points:

• The current file-based menu creation process is nice that a user does not need need to do anything extra to see a pattern added to the nav.
• your metadata suggestion is already in the works as frontmatter on a pattern's optional markdown file. Discussion and Vote: Pattern State Declaration, and other Pattern Metadata #16 order, tags, hiding patterns, a better title. It's all there in my opinion except for pattern repeating, which I don't understand completely.

So, to me, I am not convinced this concern is a problem we don't have tools for already

[georgiee]

Hello @bradfrost and @bmuenzenmeyer
thanks for reading and taking notice of this issue.

I think my general ideas and expectations of PatternLab differ a lot from what you are heading to at the moment. But I'm sure it will cross somewhen in the future again. So I will try to give you my feedback and ideas whenever something crosses my mind. I will take this as a no for this idea and close this issue.

Thanks you for the hard work guys
Regards George