Wiki source code of HTML & CSS Code Style
Last modified by Vincent Massol on 2026/09/15 13:05
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | This page lists the rules specific to HTML and CSS. The rules common to all the languages used in the XWiki project are on the [[Code Style>>Community.CodeStyle]] page. | ||
| 6 | |||
| 7 | 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. | ||
| 8 | |||
| 9 | = HTML = | ||
| 10 | |||
| 11 | The following rules must be followed: | ||
| 12 | |||
| 13 | * The HTML output produced by XWiki pages must be valid HTML 5. | ||
| 14 | * Use kebab-case for values of the {{code language="html"}}class{{/code}} and {{code language="html"}}id{{/code}} attributes | ||
| 15 | |||
| 16 | == WCAG == | ||
| 17 | |||
| 18 | The XWiki project is following the [[W3C WCAG 2.1 Guidelines>>https://www.w3.org/TR/WCAG21/]] (level AA). See the [[XWiki accessibility statement>>doc:xwiki:Documentation.UserGuide.Features.Accessibility.WebHome]] for more information about this. | ||
| 19 | |||
| 20 | The following WCAG-related rules (not verified automatically) **must** be followed (in addition to the ones automatically enforced by the [[XWiki's WCAG Tests>>Community.Testing.WCAGTesting]]): | ||
| 21 | |||
| 22 | * Only use icons along text alternatives. The text alternative can be visually hidden. | ||
| 23 | * The size of the target for pointer inputs must be at least 24 by 24 CSS pixels, in LESS use {{code language="css"}}@target-size-minimum{{/code}} [[see exceptions>>Target size exceptions]]. | ||
| 24 | |||
| 25 | The following WCAG-related rules **should** be followed: | ||
| 26 | |||
| 27 | * The size of the target for pointer inputs should be at least 44 by 44 CSS pixels, in LESS use {{code language="css"}}@target-size-recommended{{/code}} [[see exceptions>>Target size exceptions]]. | ||
| 28 | * [[Properly hide elements>>Properly hiding elements]] | ||
| 29 | |||
| 30 | = CSS = | ||
| 31 | |||
| 32 | The following rules must be followed: | ||
| 33 | |||
| 34 | * the CSS must be valid conform [[CSS 2.1 specification>>http://www.w3.org/TR/CSS21/]]. This can be tested using the [[W3C CSS Validator>>http://jigsaw.w3.org/css-validator/]] | ||
| 35 | * don't use ##!important## declarations. | ||
| 36 | ** An exception to this rule is allowed for a generic CSS class whose purpose is to force some styling (which cannot be forced otherwise). | ||
| 37 | * don't use inline style declarations | ||
| 38 | * ((( | ||
| 39 | Some properties must not be hardcoded. Instead they must use Flamingo ColorTheme variables ([[LESS variables>>doc:xwiki:Documentation.DevGuide.FrontendResources.Style variables.WebHome||anchor="HLESSvariables"]] or [[CSS properties>>doc:xwiki:Documentation.DevGuide.FrontendResources.Style variables.WebHome||anchor="HUsingCSSproperties"]]). Those properties are: | ||
| 40 | |||
| 41 | * Colors | ||
| 42 | * Font weights | ||
| 43 | ))) | ||
| 44 | * 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 {{code language="css"}}@btn-default-color{{/code}} for the text color in the default button, and {{code language="css"}}@btn-default-bg{{/code}} for its background color. | ||
| 45 | * test your code all the [[supported browsers>>doc:Community.SupportStrategy.BrowserSupportStrategy]] | ||
| 46 | * 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 | ||
| 47 | * Use kebab-case for CSS properties (and LESS variables) names. | ||
| 48 | |||
| 49 | The following recommendations could be followed: | ||
| 50 | |||
| 51 | * Properties: | ||
| 52 | ** alphabetical order | ||
| 53 | ** 2 spaces indentation | ||
| 54 | ** put a space between selector and declaration start, ex. "##a {}##" | ||
| 55 | ** put a space before the property value, ex. "background-color: @dropdown-bg;" | ||
| 56 | ** use CSS shorthands | ||
| 57 | ** use relative sizes (em, %) instead of fixed ones (px) | ||
| 58 | ** IE hacks must be removed when updating existing code (since we do not support it anymore) | ||
| 59 | ** Avoid using {{code language="css"}}display: contents{{/code}}. | ||
| 60 | * Organization: | ||
| 61 | ** comment headers for separation and grouping of different parts of the code | ||
| 62 | ** Separate adjacent rulesets with an empty line. | ||
| 63 | * Overwriting: | ||
| 64 | ** document the localization of the overwrite using "Overwrites" and "Should be in" comments | ||
| 65 | |||
| 66 | == Comments == | ||
| 67 | |||
| 68 | **Short comments** (less then 120 characters): | ||
| 69 | |||
| 70 | {{code language="css"}} | ||
| 71 | /* This is a short comment. */ | ||
| 72 | {{/code}} | ||
| 73 | |||
| 74 | **Long comments**: | ||
| 75 | |||
| 76 | {{code language="css"}} | ||
| 77 | /* This is a very long comment that wraps | ||
| 78 | on multiple lines ... | ||
| 79 | and so on. */ | ||
| 80 | {{/code}} | ||
| 81 | |||
| 82 | **Sectionning**: | ||
| 83 | |||
| 84 | This style should be used to declare sub-sections on a CSS file. | ||
| 85 | |||
| 86 | {{code language="css"}} | ||
| 87 | /** | ||
| 88 | * Section title. | ||
| 89 | */ | ||
| 90 | {{/code}} | ||
| 91 | |||
| 92 | == Tools == | ||
| 93 | |||
| 94 | * [[Firebug>>http://getfirebug.com/]] | ||
| 95 | * [[CSS Optimizer>>http://www.cssoptimiser.com/]] and [[CSS Compressor>>http://www.csscompressor.com/]] are two excellent online tools that can shrink CSS | ||
| 96 | |||
| 97 | = Testing = | ||
| 98 | |||
| 99 | See the [[Community.Testing]]. |
