Wiki source code of HTML & CSS Code Style
Last modified by Lucas Charpentier on 2026/03/11 10:23
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
3.3 | 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} |
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
 |
4.1 | 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 | |||
 |
27.1 | 7 | = HTML = |
| |
4.1 | 8 | |
 |
1.1 | 9 | The following rules must be followed: |
| |
3.3 | 10 | |
 |
10.1 | 11 | * The HTML output produced by XWiki pages must be valid HTML 5. |
| |
26.1 | 12 | * Use kebab-case for values of the {{code language="html"}}class{{/code}} and {{code language="html"}}id{{/code}} attributes |
| |
1.1 | 13 | |
| |
27.1 | 14 | == WCAG == |
| |
12.2 | 15 | |
| |
37.1 | 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. |
| |
12.2 | 17 | |
| |
22.1 | 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]]): |
 |
15.2 | 19 | |
| |
23.1 | 20 | * Only use icons along text alternatives. The text alternative can be visually hidden. |
| |
30.1 | 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]]. |
| |
12.3 | 22 | |
| |
17.1 | 23 | The following WCAG-related rules **should** be followed: |
| 24 | |||
| |
30.1 | 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]]. |
| |
29.1 | 26 | * [[Properly hide elements>>Properly hiding elements]] |
| |
17.1 | 27 | |
| |
3.1 | 28 | = CSS = |
| 29 | |||
| 30 | The following rules must be followed: | ||
| |
3.3 | 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/]] | ||
| |
39.2 | 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). | ||
| |
3.1 | 35 | * don't use inline style declarations |
| |
36.1 | 36 | * ((( |
| |
39.1 | 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: |
| |
36.1 | 38 | |
| |
36.2 | 39 | * Colors |
| 40 | * Font weights | ||
| |
36.1 | 41 | ))) |
| |
35.1 | 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. |
| |
15.2 | 43 | * test your code all the [[supported browsers>>doc:Community.SupportStrategy.BrowserSupportStrategy]] |
| |
14.1 | 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 |
| |
38.1 | 45 | * Use kebab-case for CSS properties (and LESS variables) names. |
| |
3.1 | 46 | |
| 47 | The following recommendations could be followed: | ||
| |
3.3 | 48 | |
| |
3.2 | 49 | * Properties: |
| |
3.3 | 50 | ** alphabetical order |
| 51 | ** 2 spaces indentation | ||
| |
8.1 | 52 | ** put a space between selector and declaration start, ex. "##a {}##" |
| |
31.1 | 53 | ** put a space before the property value, ex. "background-color: @dropdown-bg;" |
| 54 | ** use CSS shorthands | ||
| |
3.3 | 55 | ** use relative sizes (em, %) instead of fixed ones (px) |
| |
16.1 | 56 | ** IE hacks must be removed when updating existing code (since we do not support it anymore) |
| |
18.1 | 57 | ** Avoid using {{code language="css"}}display: contents{{/code}}. |
| |
3.1 | 58 | * Organization: |
| |
3.3 | 59 | ** comment headers for separation and grouping of different parts of the code |
| |
24.1 | 60 | ** Separate adjacent rulesets with an empty line. |
| |
3.1 | 61 | * Overwriting: |
| |
3.3 | 62 | ** document the localization of the overwrite using "Overwrites" and "Should be in" comments |
| |
3.1 | 63 | |
| |
10.4 | 64 | == Comments == |
| 65 | |||
| |
11.2 | 66 | **Short comments** (less then 120 characters): |
| |
10.4 | 67 | |
| 68 | {{code language="css"}} | ||
| 69 | /* This is a short comment. */ | ||
| 70 | {{/code}} | ||
| 71 | |||
| |
11.2 | 72 | **Long comments**: |
| |
10.4 | 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 | |||
| |
11.2 | 80 | **Sectionning**: |
| |
10.4 | 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 | |||
| |
5.1 | 90 | == Tools == |
| |
3.1 | 91 | |
| |
3.3 | 92 | * [[Firebug>>http://getfirebug.com/]] |
| |
3.1 | 93 | * [[CSS Optimizer>>http://www.cssoptimiser.com/]] and [[CSS Compressor>>http://www.csscompressor.com/]] are two excellent online tools that can shrink CSS |
| 94 | |||
| |
1.1 | 95 | = Testing = |
| 96 | |||
| |
12.2 | 97 | See the [[Community.Testing]]. |
