Naming Conventions

Overview

Type	Convention
Pattern Lab File Name	kebab-case
Component Folder	kebab-case for name; dot.case for feature
Component Naming	Keep it generic for most cases
Release Naming	SEMVER
Git Branches	feature/, bugfix/, docs/, hotfix/, release/

Pattern Lab File Name

Pattern Lab Tricks

• -hide-on-view-all-page-but-show-in-dropdown.twig
• _hide-in-dropdown-but-show-on-view-all-page.twig
• 00-use-number-prefix-to-order.twig

Note: Use increments of 5 when trying to order pages, such as 00-, 05-, 10- and so on.
Note: All patterns in the 04-pages folder are excluded from the view all page by default so do no need to be prefixed with a -.

Pages

• simple-page.twig
• complex-page.twig
• complex-page~variation-a.json
• complex-page~variation-b.json

Note: Use json data to create variations of pages with the same markup but different content. For the twig template page, leave default data such as insert content here in place of all the variables, making it obvious that it's a template.

Example

00-home-page.twig
05-search-page.twig
10-search-page~press-releases.json
15-search-page~media-coverage.json
20-details-page.twig

Component Docs

• component-name.twig
  • This documents the default component without changing any schema props
• component-name-docs.twig
  • This contains the README and Schema
• component-name--prop-name.twig
  • This documents the usage of a specific prop
• component-name--recipe-name.twig
  • This documents the specific combinations of props to achieve certain styles

Example

00-band-docs.twig
05-band.twig
schema/
  10-band--themes.twig
  15-band--sizes.twig
recipes/
  20-band--with-background-video.twig

Component Folder

Use kebab-case to handle multi-word names, use dot.case to indicate a component or component element's feature.

/src
  * _component-setting-and-tools.*
  * _component.feature.*
  * _component-element.*
  * _component-element.feature.*
  * _component-outside-library.*
  * component.*

Component Naming

1. If the component is very generic, the name should also be generic
   • Example: tooltip. You can make anything (link, image, text, card, etc) as the trigger and the tooltip activates from that trigger.
2. If the component is very opinionated, the name should also be opinionated
   • Example: nav-priority. This is not very generic, because you can't simply put anything and everything inside nav-priority. What you would not do is to call this just nav, because this type of nav has very specific and opinionated behaviors, it is not a generic navigation.
3. A collection of component would be a pattern, we should not have things like button-group and chip-list as components

@todo: 2.0 to add a Patterns folder.

Release Naming

XX.YY.ZZ → SEMVER

• XX = major version bump (breaking changes)
• YY = new features
• ZZ = bug fixes

Git

Branch Naming

All branches should begin with a directory prefix.

Branch Prefix	Branches from/merges to	Meaning
feature/*	master	Normal work, indicates a planned addition or change
bugfix/*	master	Normal work, indicates a fix for something that's broken
docs/*	master	Normal work, indicates that only documentation is affected (no source code changes)
hotfix/*	release/*	An urgent fix needed before the next scheduled release
release/*	master	A branch on which releases are created

After the prefix, the branch should include the JIRA ticket number followed by a few key words describing the PR.

Example

feature/DS-106-simplify-labels

Commit messages

Commit messages should follow this format: [JIRA ticket number]: [Short message]

Example

DS-106: Simplify auto labels

• Put a colon after the issue number
• DON't end the message with a period (unless your name is Kelly...)
• Always start with a verb and use imperative tense (e.g. "Add", "Fix", etc -- NOT "Adds", "Fixes" or "Added", "Fixed").
• The full message should not exceed 72 characters. List any additional details in the commit message body after a blank line.

PR Titles

PR titles should follow this format: [JIRA ticket number] [JIRA ticket title]

Optionally, you may use a short description instead of the ticket title (especially when you have multiple PRs for the same issue).

Example

DS-106 Simplify and conform git directories and labels