DOC: Code Guidelines for HTML/CSS

[AdamJ]

This issue tracks the progress of the creation of the CodeGuidelines.md file that will govern the HTML and CSS for fabric8io/fabric8-ui and fabric8io/fabric8-planner.

The file can be found here: CODEGUIDELINES.md, or can be viewed on the fabric8-ux site.

[AdamJ]

Suggest CSS Property Order:

css property order

Related property declarations should be grouped together following the order:

1. Positioning
   • position
   • top
   • right
   • bottom
   • left
   • z-index
2. Box model
   • display
   • float
   • width
   • height
   • max-width
   • max-height
   • min-width
   • min-height
   • padding
   • padding-top
   • padding-right
   • padding-bottom
   • padding-left
   • margin
   • margin-top
   • margin-right
   • margin-bottom
   • margin-left
   • margin-collapse
   • margin-top-collapse
   • margin-right-collapse
   • margin-bottom-collapse
   • margin-left-collapse
   • overflow
   • overflow-x
   • overflow-y
   • clip
   • clear
3. Typographic
   • font
   • font-family
   • font-size
   • font-smoothing
   • osx-font-smoothing
   • font-style
   • font-weight
   • hyphens
   • src
   • line-height
   • letter-spacing
   • word-spacing
   • color
   • text-align
   • text-decoration
   • text-indent
   • text-overflow
   • text-rendering
   • text-size-adjust
   • text-shadow
   • text-transform
   • word-break
   • word-wrap
   • white-space
   • vertical-align
   • list-style
   • list-style-type
   • list-style-position
   • list-style-image
   • pointer-events
   • cursor
4. Visual
   • background
   • background-attachment
   • background-color
   • background-image
   • background-position
   • background-repeat
   • background-size
   • border
   • border-collapse
   • border-top
   • border-right
   • border-bottom
   • border-left
   • border-color
   • border-image
   • border-top-color
   • border-right-color
   • border-bottom-color
   • border-left-color
   • border-spacing
   • border-style
   • border-top-style
   • border-right-style
   • border-bottom-style
   • border-left-style
   • border-width
   • border-top-width
   • border-right-width
   • border-bottom-width
   • border-left-width
   • border-radius
   • border-top-right-radius
   • border-bottom-right-radius
   • border-bottom-left-radius
   • border-top-left-radius
   • border-radius-topright
   • border-radius-bottomright
   • border-radius-bottomleft
   • border-radius-topleft
   • content
   • quotes
   • outline
   • outline-offset
   • opacity
   • filter
   • visibility
   • size
   • zoom
   • transform
   • box-align
   • box-flex
   • box-orient
   • box-pack
   • box-shadow
   • box-sizing
   • table-layout
   • animation
   • animation-delay
   • animation-duration
   • animation-iteration-count
   • animation-name
   • animation-play-state
   • animation-timing-function
   • animation-fill-mode
   • transition
   • transition-delay
   • transition-duration
   • transition-property
   • transition-timing-function
   • background-clip
   • backface-visibility
   • resize
   • appearance
   • user-select
   • interpolation-mode
   • direction
   • marks
   • page
   • set-link-source
   • unicode-bidi
   • speak

[SMahil]

@mindreeper2420 I have some suggestions:

For General Formatting

1. Use only lowercase
2. Comments: Explain code as needed, where possible. Avoid heavily commented HTML Code

For HTML Attribute order

• Put class attribute first (developers read/write this most often).
• Put id attribute second (important if it’s defined).
• Everything else is alphabetical.
• Put data-* attributes last (alphabetical). But there can be some exceptions. When an attribute is critical to defining an element put it first to improve readability. For e.g.

  
  <!-- The "type" defines the element's behavior. -->
  <button type="" class=""></button>

[SMahil]

For Class Names Naming convention How about using BEM Methodology? Instead of underscores we can use single hyphens

[SMahil]

As you( @mindreeper2420 ) said using io as prefix is the great idea but what about planner/platform specific components? We should also come up with prefixes as that needs to be in guidelines

[SMahil]

I have another point on lengthy HTMLs (horizontally). Can we limit the HTML line length for better readability ?

[AdamJ]

@SMahil Responses to your points below :)

1. Agree on General Formatting and HTML Attributes ordering. Those are definitely things that we can define that will also be easy to keep consistent.

2. I thought about the BEM Methodology (the PatternFly 5 Code Guidelines state that, but I commented them out when I forked them), but wasn't sure if we should go down that path right now. I'd be for it, just need to get the timing right.

This is what PatternFly 5 is recommending:

---

BEM

PatternFly follows the BEM methodology. It's a way to decouple CSS from HTML, and modularize class names so they can be extended.

Class name structure follows the {{pf-block}}__{{element}}--{{modifier}} structure:

.pf-block__element--modifier {}

Example:

<div class="pf-panel pf-panel--collapsible">
  <div class="pf-panel__title">
    <h1>Heading</h1>
  </div>

  <div class="pf-panel__content">
    <p>Lorem ipsum dolor sit amet.</p>
  </div>
</div>

.pf-panel {}                      // Block
.pf-panel--collapsible {}         // Modifier of block

.pf-panel__title {}               // Element

.pf-panel__content {}             // Element
.pf-panel__content--unpadded {}   // Modifier of element

Why it’s better

• All the selectors have same specificity.
• Every element is defined via a block.
• Every modifier is defined via a block or element.
• Each class name imparts structural info without binding to exact HTML.

---

3. As all of these are consumed by IO, I'd either stick with that, or go with an f8- prefix for everything, as all of these areas are part of the Fabric8 organization. That would clearly separate what is specific to fabric8 and what is not. I think that breaking it down into Platform/Planner prefixes would decrease the extensibility of the overall environment.

4. I started working on a linter and set the max character line for Less files to 100 characters. We can do something similar for the HTML, but extend that to the ordering and formatting that you mentioned. A good piece of that would be specifically written in our code guidelines document.

[catrobson]

Ready to close or still in review?

[AdamJ]

@dgutride @dlabrecq any thoughts on the Code Guidelines that we've written up?

[dlabrecq]

Does Patternfly 5 have a code guidelines file available for reference? I'm wondering if we can point to that instead or at least have a pointer to it as the gold standard?

Looking at the proposed CSS property grouping order and seems difficult to follow. I don't know if folks will get the ordering right each time? Unless everyone understands that 'content' comes before 'quotes' and 'word-spacing' comes before 'color'?

You might want to note why we're following that particular order? If we're are expected to place 'word-spacing' before 'color', it would be good to understand why that makes a difference. That is, why are the selector groupings not alphabetical?

I'm not a fan of 100 chars limits, especially for HTML files with long selector names? I find 120 to be a more reasonable number. If the Angular code is allowed to be greater than 100 chars, other files should be the same. The fabric8-ui linter is 120

[AdamJ]

@dlabrecq this was copied from the PatternFly 5 code guidelines here: https://github.com/patternfly/patternfly-css/blob/master/CODE-GUIDELINES.md, but with our additions/alterations. I added a reference to it at the bottom of the file, but I can include one at the top as well.

On the CSS grouping order, PatternFly 5 will be following the Field CSS Manual, which this guideline has just taken the pieces out and put them into one list. The Field Manual does break them out in an easier to read format, so we can just refer to that.

Regarding the 100 character limit, that is coming from the Less Hinter that we will be using: lesshint. The default there is 100, so that is what I put for our limit as well. That can be changed, though I'd like to have a limit that isn't too out there.

[dlabrecq]

The Field CSS manual shows appears to be alphabetical within groups -- color is before any other property. Just wanted to be clear about the proposed order because your suggested groupings were not alphabetical.

120 chars is not unreasonable for HTML.

[AdamJ]

PR for updating the Code Guidelines with information on Field CSS Manual, structure and HTML character limit: https://github.com/fabric8io/fabric8-ux/pull/508.

[AdamJ]

With the latest PR merged, I'm going to close this issue. We can open another if updates are needed, once we start to implement the guidelines across the platform.