HTML & CSS Guidelines (v1.0)

Google Doc (Contains same) - https://docs.google.com/document/d/1RqZqAQAmUhJqaMCL26iIvx9MS03MxKbby9My_Fbt1Do/edit#  

JIRA Card - https://project-sunbird.atlassian.net/browse/SB-6076

Goal

• To bring consistency in code quality and standards across the Project.

• To set minimum quality standards.

• An effective tool for measurements in code reviewing.

• Make easy onboarding for newcomers.

Scope areas

1. The responsive/ Mobile-first approach

2. Cross-browser compatibility

3. SEO & Social shareability

4. Web Accessibility

5. Performance

6. Security

7. Quality code -  Coding style

8. Good commenting practices

Mandatory Process

• Code Review - PR’s with HTML & CSS changes must be reviewed & approved by the concerned person.

• Code Review Parameters

•  

  • Reusable code = High

  • Functional Issues = High

  • Mobile-first approach = High

  • Naming Conventions = High

  • Code formatting = Medium

  • Error Handling / Fallback for old browsers = High

  • Code organized (written on correct location) = High

• Reuse code - Writing CSS code must be completely avoided. The approach should be -

•  

  • Check - Look for a solution in Ng2-semantic & Semantic UI and Sunbird CSS Library.

  • Contribute - If solution not found in either of the libraries -> Try to write reusable generic class and contribute it to Sunbird CSS Library (Reusables folder).

CSS Formatting

• When using multiple selectors in one rule declaration, give each selector its own line.

• The code should be properly intended - use 1 soft tab (2 spaces).

• Put a space before the opening brace { in rule declarations.

• In properties, put a space after, but not before, the : character.

• Put closing braces } of rule declarations on a new line.

• The code inside media queries should be 1 soft tab intended.

• Declaration Order for properties - Put declarations in order to achieve consistent code. Related property declarations should be grouped together following the order:

  • Positioning

  • Box model

  • Typographic

  • Visual

• Quotation Marks

•  

  • Use single ('') rather than double ("") quotation marks for attribute selectors and property values.

  • Do not use quotation marks in URI values (url()).

• Comments -

  • Uses of z-index.

  • Compatibility or browser-specific hacks.

  • TODO - Mark todos and action items with TODO. Append action items after a colon as in TODO: action item if the code needs refactoring later.

•  

  • Prefer comments on their own line.

  • Write detailed comments for code that isn't self-documenting:

CSS Naming Convention

Classes naming should be more predictable to use and hence it needs to be consistent. Naming convention to followed -

• Utility / Helper reusable classes (Typically single property classes) Name of such classes should be abbreviation of property followed by value. Eg -

•  

  • Padding 10px around all direction should be p-10. While only Padding top 10px should be pt-10. For vertical padding 10px should be py-10.

  • Display flex should be d-flex

  • Border radius 0 for all corner should be named as br-0 however if only top right corner radius is 0 then class should be brtr-0

• Extending Semantic UI framework components - Such classes should follow the same naming convention Semantic UI follows. Eg -

•  

  • Adding a small size modal should have modifier class small

  • Adding one more color button should have classname of color. If name is multi-word then class should be camelCased.  Eg - arcticBlue

CSS code organisation / SCSS Implementation (#SB-8105)

https://docs.google.com/document/d/1te1B983SdMEkN2MPh__WqhU0kaNLR3D4OAFXONcZGBo/edit

CSS Best Practices

• Specificity Problems -

• Avoid !important

• Never use IDs in CSS, ever. They have no advantage over classes (anything you can do with an ID, you can do with a class), they cannot be reused, and their specificity is way, way too high. Even an infinite number of chained classes will not trump the specificity of one ID.

• Do not nest selectors unnecessarily. If .header-nav {} will work, never use .header .header-nav {}; to do so will literally double the specificity of the selector without any benefit. ( Semantic follows this bad practice )

• Do not qualify selectors unless you have a compelling reason to do so. If .nav {} will work, do not use ul.nav {}; to do so would not only limit the places you can use the .nav class, but it also increases the specificity of the selector, again, with no real gain.

• JavaScript hooks - Avoid binding to the same class in both your CSS and JavaScript. Conflating the two often leads to, at a minimum, time wasted during refactoring when a developer must cross-reference each class they are changing, and at its worst, developers being afraid to make changes for fear of breaking functionality. We recommend creating JavaScript-specific classes to bind to, prefixed with .js-

• Never @import css file.  Never import css file within css file because it downgrades the performance of the site. ( Currently Semantic imports Roboto font in this way and Roboto font is not used at all on the portal hence this needs fixed. )

• No random big Z-index. Never give random or very high z-index. Check siblings z-index and +1 to it. Giving random high z-index can cause issues later after some complexity is increased.

• Horizontal & Vertical Box Centering -

Avoid doing box vertical & horizontal centering by adjusting left and top properties. Use transform: translate(-50%, -50%) to avoid rewriting media specific css.

Bad Code

      Good Code

• Avoid Hard Coded Height for background images or videos-

Avoid mentioning height. Try to use aspect ratios to avoid writing media queries.

Bad Code

    Good Code

• Avoid Hardcoded height to any component like header, footer, card etc.  Components will shrink and expand and their height will increase or decrease based on device size.  Let component take their natural space. In this way you won't have to write code in several media queries.

• Use shorthand properties where possible.

Bad Code

Good Code

• 0 and Units

Omit unit specification after “0” values, unless required. Do not use units after 0 values unless they are required. Eg -

• Avoid workaround values for width, padding and margin

• Bad Width: Eg -  93% or 86% or 49% etc

•  

  • Bad Margin & Padding: Eg - 11%, 3px etc

  • Bad Negative Margin: -2px etc

Eg 1: If there are 2 elements .right with width 30px and .left with rest of the space

Bad Code

     Good Code

 In this way you can avoid writing media specific codes

 Eg 2: try to avoid minor adjustment padding - margin

 Bad Code

• Reusable generic classes

•  

  • Make better use of CSS cascading properties by creating generic reusable classes.

  • Separate structure and skin. This will help in creating multiple variations of the same thing. Eg - Buttons, Modals etc.

• Responsive / Mobile First - A mobile-first approach to styling means that styles are applied first to mobile devices. Advanced styles and other overrides for larger screens are then added into the stylesheet via media queries. This approach uses min-width media queries.

•  

  • Avoid writing media queries (max-width: - - -) & (orientation: - - -).

  • Do not repeat properties in media queries. Override the changing property only.

      Bad Code

     Good Code

• Effective use of SCSS

  • Use Mixins effectively for code consistency

  • Use variables effectively for theming

  • Use @imports & @extends for proper code organization & reusability.