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