This document covers some basic conventions that are used in XWiki codebase. Please read over this document and make sure your code conforms to the rules here.

HTML

The following rules must be followed:

• The HTML output produced by XWiki pages must be valid HTML 5.
• Use kebab-case for values of the class and id attributes

WCAG

The XWiki project is following the W3C WCAG 2.1 Guidelines (level AA).

The following WCAG-related rules (not verified automatically) must be followed (in addition to the ones automatically enforced by the XWiki's WCAG Tests):

• Only use icons along text alternatives. The text alternative can be visually hidden.
• The size of the target for pointer inputs must be at least 24 by 24 CSS pixels, in LESS use @target-size-minimum see exceptions.

The following WCAG-related rules should be followed:

• The size of the target for pointer inputs should be at least 44 by 44 CSS pixels, in LESS use @target-size-recommended see exceptions.
• Properly hide elements

CSS

The following rules must be followed:

• the CSS must be valid conform CSS 2.1 specification. This can be tested using the W3C CSS Validator
• don't use !important declarations
• don't use inline style declarations

• Some properties must not be hardcoded. Instead they must use ColorTheme variables (use the up to date Flamingo ColoTheme variables). Those properties are:

  • Colors
  • Font weights
• All colors must be defined for either a foregound or a background. To name those, use the “color” word in the variable name for foreground color, and the “background” or “bg” words in the variable name for background colors. For example, we use @btn-default-color for the text color in the default button, and @btn-default-bg for its background color.
• test your code all the supported browsers
• the unit must be omitted when the value is zero (i.e., width: 0; is ok, and width: 0em; is not) 1) the unit is optional in this case 2) it is more concise

The following recommendations could be followed:

• Properties:
  • alphabetical order
  • 2 spaces indentation
  • put a space between selector and declaration start, ex. "a {}"
  • put a space before the property value, ex. "background-color: @dropdown-bg;"
  • use CSS shorthands
  • use relative sizes (em, %) instead of fixed ones (px)
  • IE hacks must be removed when updating existing code (since we do not support it anymore)
  • Avoid using display: contents.
• Organization:
  • comment headers for separation and grouping of different parts of the code
  • Separate adjacent rulesets with an empty line.
• Overwriting:
  • document the localization of the overwrite using "Overwrites" and "Should be in" comments

Comments

Short comments (less then 120 characters):

Long comments:

Sectionning:

This style should be used to declare sub-sections on a CSS file.

Tools

• Firebug
• CSS Optimizer and CSS Compressor are two excellent online tools that can shrink CSS

Testing

See the Testing.