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.

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 following rule has not been validated yet.

  Icon fonts must have a role="img" attribute (see Providing a Semantically Identified Icon Font with role=img). For example:

  xwiki.iconset.render.wiki = {{html clean="false"}}<span class="fa fa-$icon" role="img"></span>{{/html}}
• 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:
  • Hiding visually and semantically:
        E.g. an element disappearing from the UI after a user interaction; a label or description only for screen readers, referenced via aria-labelledby or aria-describedby (see this WAI-ARIA practice about naming elements).
    • CSS: Use the property and value: display: none.
    • HTML:
      • For inputs, use the attribute and value: type="hidden".
      • For others, use the boolean attribute: hidden ¹.
  • Hiding visually and showing semantically:
        E.g. a label for an interactive element that would just clutter the visual UI.
    • HTML: Use the class: sr-only. (abbreviation of “screen reader only”)
  • Hiding semantically and showing visually:
       

    This technique should only be used on an element that could be removed without changing the user experience in any other way than the presentation.

    • Example of proper usage: The avatar picture to display a ‘User’ entry in a table. It’s always paired with the name of the user, so it’s not an issue to hide it from assistive technologies. In this case it’s better, since the information is repeated in two elements.
    • Example of grey area use: A separator in a list. The separator can be seen as nothing but a blank space, but for the user it implies a ‘separation’ between two groups of list elements. This separation should be reflected on a semantic meaning, hiding the separator is not the best solution.
    • Example of a clear misuse: Hiding a picture used to illustrate a <p>. Accessible content is content that conveys the same meaning no matter the technology used to read it. The picture has a purpose and meaning, and hiding this from assistive technologies prevents AT users from getting the full experience.
           
      Use only on leave nodes of the DOM tree because this technique does not hide the content but only the semantics of the node. If you want to hide more than a leaf node, it’s very probable that you should consider hiding it visually too. If it’s still not possible, using the aria-hidden attribute is the last resort.
    • HTML: Use the attribute and value: role="presentation".

Target size exceptions

• The target is inline, then its height is constrained by line-height.
• There is enough non interactive space around the target so that we could grow it the required size without overlapping any other target. The target itself can be smaller in this case.
• Two targets have the same function, only one of them needs to have the required size.
• Target size is determined by the user.
• The target presentation is essential for the information being conveyed (up to interpretation…).

A more precise definition of these exceptions is available at Understanding WCAG SC 2.5.8 > Exceptions.

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
• don't hard code colors in properties - use ColorTheme variables
• 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 {}"
  • use of 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
• 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.

Issues

• We currently don't have a naming convention

Tools

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

Testing

See the Testing.

1. ^ This means avoiding using a dedicated CSS class such as `hidden`.