Standardize CSS patterns

[shockey]

Swagger-UI's stylesheets are adequate overall, but there are several corners where we have CSS patchwork.

Bringing more consistency, safety, and clarity to this part of the project will bring about the following:

• Contributors will be able to more readily understand how to make changes to the project's styles
• Users will be able to reason about custom styles more easily
• User-written selectors for custom styles will be less likely to break, as naming will be less arbitrary
• End-to-end tests will be easier to comprehend

Current Behavior

My current pain points:

• class names and inheritance are inconsistent
• one-off classes and libraries are used (I've committed this sin, see our use of Tachyons)
• wide-reaching styles cut across concerns in an unpredictable way.

Possible Solution

• Classify stylesheets and existing styles into two types: those that affect global styles (a specific element, a class, anything that cross-cuts component concerns), and those that are bound to a specific component
• Organize stylesheets so that each component has its own file: for example, Markdown would have an accompanying _markdown.scss stylesheet
• Namespace each component's styles under a standardized class: for example, all the rules in _markdown.scss would be contained within .Markdown, .MarkdownComponent, or something similar
  • Bonus points: contain these styles within a specific component, so that a p style for a parent component wouldn't affect p elements in that component's children
• Agree on, refactor to, and document a CSS naming methodology
  • We use BEM in many places, so that's the path of least resistance.

Context

I wrote this ticket so I could spin my thoughts about #4458 into an actionable item.

[heldersepu]

Yes big +1 and while you are at it maybe fix all the alignment issues (#4241)...
I looked into it, but got dizzy looking at the CSS

[shockey]

More thoughts:

• BEM loosely mapped as block:component
• one block per SCSS file

[Rody-Kirwan]

Absolutely agree. I think this is the most maintainable way of dealing with stylesheets.

You could go one step further and relocate component-specific stylesheets to the components directory, alongside it's counterpart. Obviously quite a big change in one go, but can be a relatively simple to do in increments.

Just a thought!

Example

components/model
  -- model.jsx
  -- model.scss
  -- index.js // exports the component to maintain existing filepaths