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 https://github.com/authgear/authgear-server/pull/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 https://github.com/authgear/authgear-server/pull/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. https://github.com/authgear/authgear-server/pull/3614#discussion_r1451976049 https://github.com/authgear/authgear-server/pull/3613#discussion_r1452898325
• Remove unnecessary divs. https://github.com/authgear/authgear-server/pull/3613#discussion_r1452898198

Use gap for spacing.

See https://github.com/authgear/authgear-server/pull/3613#discussion_r1452897671

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

See https://github.com/authgear/authgear-server/pull/4662#discussion_r1735509674

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: https://github.com/authgear/authgear-server/pull/4804#discussion_r1792733226

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

• https://github.com/authgear/authgear-server/issues/3628
• https://github.com/authgear/authgear-server/issues/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.