Uswds: Audit BEM notation

[maya]

Make sure we are using accurate BEM notation throughout USWDS 2.0.

A helpful guide: https://seesparkbox.com/foundry/bem_by_example

USWDS classes that begin with .usa-*

https://gist.github.com/maya/17f1b37d5320713877159cc0b4e3c8ff

To investigate

.usa-button-unstyled
.usa-unstyled-list
.usa-input-error-message
.usa-input-label-helper
.usa-input-label-required
.usa-media-link
.usa-social-link
.usa-form-hint
.usa-input-list
.usa-content-list
.usa-font-lead
.usa-dark-background
.usa-footer-* ...
.usa-nav-* ...
.usa-mobile-nav-active

[thisisdano]

That sparkbox guide is really nice.
I _think_ we've implemented our own BEM consistent with that guidance, so I hope there are only a few instances where stuff is out of whack.

[thisisdano]

One known inconsistency is with usa-unstyled-list. Currently this is a standalone block instead of a modifier of usa-list (à la usa-list.usa-list--unstyled). I believe this is for simplicity's sake. But there's a fair argument to be made that the benefits of simplicity are outweighed by the cognitive burden of the inconsistency.

.usa-button-unstyled is the same (but different). If we leave them as standalone blocks, they should both have the same naming system (probably something like usa-unstyled-button -- that would be consistent with usa-unstyled-list and usa-dark-background which are named that way to prevent being confused as modifiers).

[thisisdano]

Of course, maybe usa-button-unstyled should just be regular BEM — usa-button--unstyled.

I'm inclined to leave usa-dark-background as is since usa-background is currently meaningless.

[thisisdano]

@maya what do you think about .usa-button-unstyled and . usa-unstyled-list?
I _think_ I'd like to just go ahead and BEM them but I'm not 100%.

[maya]

.usa-button--unstyled and .usa-list--unstyled make the most sense to me for consistency sake.

[thisisdano]

OK, working on unstyled lists and button here: https://github.com/uswds/uswds/issues/2956

[maya]

Looking through some classes that didn't seem to use BEM, this is what I found:

• [ ] .usa-button-unstyled
  TODO .usa-button--unstyled
• [ ] .usa-unstyled-list
  TODO .usa-list--unstyled
• [ ] .usa-input-error-message
  This is within .usa-form-group. .usa-input is an element following this. Should it be .usa-input__error-message?
• [ ] .usa-input-label-helper
  This is label text that is placed inside label text. Suggest .usa-label--helper? (duplicate of .usa-form-hint)
• [ ] .usa-input-label-required
  Turns text red, sort of a "hidden" class. .usa-label--required? Should it also add an asterisk?
• [ ] .usa-media-link
  is media-link its own component or a modifier of a link? e.g. .usa-link--media
• [ ] .usa-social-link
  is social-link its own component or a modifier of a link? e.g. .usa-link--social
• [ ] .usa-form-hint
.usa-form__hint? (duplicate of .usa-input-label-helper)
• [ ] .usa-input-list
  This is the list element that contains radio buttons and checkboxes, effects line-height
• [ ] .usa-content-list
  This adds max-width that was previously used on list elements before we added max-width to them within usa-prose, previously a max-width was left out. Remove?
• [ ] .usa-font-lead
  Suggest usa-font--lead, usa-text--lead, usa-lead-text?
• [ ] .usa-dark-background
  Could also be .usa-background--dark
• [ ] .usa-footer-* ... TBD
• [ ] .usa-nav-* ... TBD
• [ ] .usa-mobile-nav-active
  there is no mobile-nav class, this is sort of a one-off. but could be written .usa-mobile-nav--active

[thisisdano]

Let's set aside an hour to talk these through.

[thisisdano]

| current | suggested | status
| --- | --- | ---
| .usa-button-unstyled | .usa-button.usa-button--unstyled | #2956
| .usa-unstyled-list | .usa-list.usa-list--unstyled | #2956
| .usa-input-error-message | .usa-form__error-message | —
| .usa-input-label-helper | .usa-form__helper | —
| .usa-input-label-required | .usa-form__label.usa-form__label--required | —
| .usa-media-link | dunno what this one is... | —
| .usa-social-link | keep as is | n/a
| .usa-form-hint | .usa-form__hint | —
| .usa-input-list | .usa-form__input-list | —
| .usa-fieldset | .usa-form__fieldset | —
| .usa-content-list | remove | —
| .usa-font-lead | .usa-intro | —
| .usa-dark-background | keep as is | n/a
| .usa-footer-* | ? | ?
| .usa-nav-*| ? | ?
| .usa-mobile-nav-active | leave as is? could be a js- class as it's applied to <body> | —
| .usa-menu-btn | usa-button.usa-button--menu | —

Should form subcomponents be subcomponents of usa-form like .usa-form__input? They'll never really appear anywhere else...

| current | suggested
| --- | ---
| .usa-checkbox | .usa-form__checkbox
| .usa-checkbox-input | .usa-form__checkbox-input
| .usa-checkbox-label | .usa-form__checkbox-label
| .usa-fieldset | .usa-form__fieldset
| .usa-form-group | .usa-form__group
| .usa-form-group--day | .usa-form__group--day
| .usa-form-group--error | .usa-form__group--error
| .usa-form-group--month | .usa-form__group--month
| .usa-form-group--year | .usa-form__group--year
| .usa-form-hint | .usa-form__hint
| .usa-input | .usa-form__input
| .usa-input--inline | .usa-form__input--inline
| .usa-input--medium | .usa-form__input--medium
| .usa-input--small | .usa-form__input--small
| .usa-input--success | .usa-form__input--success
| .usa-input--error | .usa-form__input--error
| .usa-input-error-message | .usa-form__error-message
| .usa-input__label-helper | .usa-form__helper
| .usa-input__label-required | .usa-form__required
| .usa-input-list | .usa-form__input-list
| .usa-label | .usa-form__label
| .usa-label--error | .usa-form__label--error
| .usa-legend | .usa-form__legend
| .usa-memorable-date | .usa-form__memorable-date
| .usa-radio  | .usa-form__radio
| .usa-radio__input | .usa-form__radio-input
| .usa-radio__label | .usa-form__radio-label
| .usa-range | .usa-form__range
| .usa-select | .usa-form__select
| .usa-textarea | .usa-form__textarea

[maya]

No, the form subcomponents don't need a form prefix, they can stand on their own. Consider reviewing https://design-system.service.gov.uk/components/ as an example.

[maya]

.usa-media-link is a link that's an image (e.g. for logos).

[thisisdano]

The form components don't _need_ one, but it actually fixes some of the edge cases and makes it all seem more consistent.

[maya]

What are the edge cases? Let's look at those and see how we can make it work.

As Harry Roberts mentions: "Just because something happens to live inside a block it doesn’t always mean is is actually a BEM element." And based on what others are doing (GOV.UK, Australian Design System and CMS's Design System), it seems it's taking further than it needs to.

I think the current approach .usa-radio and .usa-radio--input is correct. And your suggested .usa-form__radio and .usa-form__radio-input is incorrect bc radio-input is not its own component and breaks the relationship between its actual component usa-radio.

[thisisdano]

I think the edge case are

• .usa-input-error-message
• .usa-input-label-helper
• .usa-form-hint
• usa-input-list

[maya]

Based on that list and a few others, here is what I suggest:

| current | suggested
|--|--|
| .usa-input-error-message | .usa-error-message
| .usa-input-label-required | .usa-label--required
| .usa-form-hint + .usa-input-label-helper | .usa-hint
| .usa-content-list | Remove
| .usa-font-lead | .usa-intro
| .usa-mobile-nav-active | .usa-js-mobile-nav--active
| .usa-input-list | leave as is, or remove it and remove the <ul> element it's in

.usa-hint and .usa-error-message could potentially have a prefix but could also stand on their own.

[thisisdano]

That sounds good to me — as long as we're writing the CSS well and keeping everything appropriately flat this'll work. I think we just want to make sure that something like error-message wouldn't migrate somewhere else and need unique styling.

The ul in usa-input-list must've been there for some kind of specificity thing, let's see if it's still required.

[maya]

I think the ul was there to make it a semantic list but after looking around a few other places, it doesn't seem like it needs to be there.

[maya]

Do you think .usa-intro is specific enough for the lead text? In that we won't have another component called .usa-intro in the future that would be something different?

[thisisdano]

As well as I understand it, BEM is a way of being explicit about _dependencies_ in a way — and making sure that components are clear about how modular they are and where they can be used. A long as we follow that general guidance (that is, no unexpected contextual styling) I think we can feel good about our naming.

[maya]

I feel good about the naming overall, was just wondering if .usa-intro was the best name and wasn't too general to describe the lead paragraph.

[thisisdano]

As for intro — the lead is not really a lead (or lede). It's more accurately a deck (dek) or an intro. The lead is the first paragraph of a piece, where the main idea is expressed (i.e. "burying the lead" by putting the big news reveal too far into the piece). And deck is so technical, it feels out of place. (This is mostly my understanding of the terms: https://underthecurve.github.io/jekyll/update/2016/12/29/hed-dek-led-graf.html)

[maya]

Done in #2972 and #2974.