UI v2 coding guidelines

[louischan-oursky]

We have 2 levels of theming.

• The first level is defined in base.css.
• The second level is defined in the component CSS.
• Take this as example [DEPS #4640] Implement authui v2 navbar #4662
• --navbar__title-font-family is the second level.
• --typography-title-large__font-family is the first level.

We borrow BEM naming convention to name the CSS variables.

• Take this as example [DEPS #4640] Implement authui v2 navbar #4662
• The component file called navbar.css, so the component name is navbar.
• The CSS variables of this component must start with --navbar_.
• You define a CSS variable for each CUSTOMISABLE property. When you are in doubt, you prefer not introducing a CSS variable. We can always add it later.
• --navbar__some-meaningful-css-property
• --navbar__some-meaningful-css-property--variant

Prefer tablet: over @media

HTML semantics is important.

• Use appropriate elements. Add password input component  #3614 (comment) Add alert message template #3613 (comment)
• Remove unnecessary divs. Add alert message template #3613 (comment)

Use gap for spacing.

See #3613 (comment)

Use ltr: and rtl: when you use explicit left/right.

See #4662 (comment)

Verbs

• create, delete, change, view
• add, remove, change, view

Always think about when the case when javascript is disabled

• The HTML should be written in a way that javascript could be disabled.
• The functionality implemented by javascript is add-on. That is even without javascript, the UI should also work, with degraded UX, of course.
• Example: [Settings v2] Use history back for settings v2 pages navbar #4804 (comment)

panic with error

Instead of panic("some string"), panic(fmt.Errorf("some string")). The rationale is that when you are the person who recover(), you want to get an error instead of a string. You can further call errors.As and errors.Is or any other errors processing functions on the recovered error.

[louischan-oursky]

Follow up issues

• Auth UI V2 - Output dir on html element #3628
• Auth UI V2 - Make existing components or layout writing-mode friendly #3630

[louischan-oursky]

@tung2744 @IniZio @Ngkaokis Added Point 11.

[louischan-oursky]

Added Point 12.

[fungc-io]

@louischan is this documented? can I close it?

[louischan-oursky]

Let me close this. We can refer to this issue when we need it in the future.

[rickmak]

We should move the agreed content to CONTRIBUTING.md.