Class Naming Conventions

• 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 an item in a collection?
  • -item
• How to name an item's sub-elements
  • -itemLabel
  • -itemLink
• How to name nested lists?
  • If it looks different, name it different.
    • Name the inner-most list of items a completely different thing
  • If it looks the same, simply nest the component
• UI icons or icons nested in components deserve their own class

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