Class Naming Conventions

SUIT CSS

Our naming convention is based on SUIT: https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md

How to name a container of various and sundry items

• -ItemGroup, where Item is the class of items being grouped
  • .spectrum-FieldGroup
  • .spectrum-ButtonGroup
• Grouped items don't need to have special classnames and can be targeted directly

How to name a collection and its items?

The component name for a collection of something should be named according to the UI design pattern it represents -- no fancy suffixes are required.

• Collection of tabs: .spectrum-Tabs
• Collection of menu options: .spectrum-Menu
• Collection of miller columns: .spectrum-MillerColumns

Items in collections, however, should be consistently named as follows:

• Tab: .spectrum-Tabs-item
• Menu option: .spectrum-Menu-item
• Miller column: .spectrum-MillerColumns-item

Although you may be tempted to call a Tab .spectrum-Tab, it's inconsistent with other collections whose items aren't given individual names.

How to name an item's sub-elements

Sub-elements inside of collection items should be camelCase, prefixed with item.

• spectrum-Tabs-itemLabel

How to name nested lists?

If it looks different, name it different.

If the inner-most list is different than the outer list, it ought to be a separate component, such as in the case of .spectrum-MillerColumns. The column is given the .spectrum-MillerColumns-item class, and the list within it is given the .spectrum-FileList class, with .spectrum-FileList-items inside of it.

If it looks the same, simply nest the component

If the nested list is visually identical at all levels, simply nest the component within itself to go a level deeper, such as in .spectrum-TreeView.

How to target nested icons?

Don't just target .spectrum-Icon, UI icons or icons nested in components deserve their own class, such as .spectrum-Accordion-indicator.

Header vs Heading vs Title

Header

A header is a logical group of mixed content (text, buttons, icons, etc) that appears at the top of something.

Heading

A heading is a text-only bit that denotes a sub-section (a chapter).

Title

A title is the overall name of something (the book). A title can appear in a header, as in the Dialog and Calendar.

Misc Notes

We updated the naming of some components and sub elements to be more consistent, and recorded the changes and reasoning into rules:

• How to target sub-elements that are already their own components
  • .spectrum-ActionMenu-popover
    • when used inside of another component and changed in a way that’s unique to that component, but there is a possibility of the changed component being nested within itself or used more than once
    • when targeting the element by its classname would cause excessive and unnecessary specificity
    • i.e. Tooltip that’s inside of a wizard to indicate the name of a step, but you want to allow other tooltips that should not have the custom CSS
  • .spectrum-ActionMenu .spectrum-Popover
    • when used inside of another component and changed in a way that’s unique to this component, target with descendant selector
  • .spectrum-Popover--someVariant
    • when used inside of another component and changed in a way that’s common between components, add a variant
    • i.e. same changes required inside of ActionMenu AND inside of Dropdown, then add a variant
• option vs item: Should all options be items?
  • Everything should be items
• Chevron vs icon vs indicator vs separator
  • icon when conveying information
    • the type of of an Alert
    • the action performed by a button
      • discloses menu
      • deletes thing
    • has children
  • separator when separating
    • between breadcrumbs
  • indicator when indicating state
    • on accordion
• When to use .is-state
  • .is-selected in the “down” state
    • for a button that triggers a menu, when the menu is open, the button .is-selected
  • .is-focused
    • only when required because :focus-within is not available in the browser