Wiki source code of HTML & CSS Code Style

Last modified by Lucas Charpentier (Sereza7) on 2024/03/25 11:16

Show last authors
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).
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 * don't use inline style declarations
35 * don't hard code colors in properties - use [[ColorTheme variables>>extensions:Extension.Color Theme Application||anchor="HUsingColorThemesvariables"]] (use the up to date [[Flamingo ColoTheme variables>>doc:extensions:Extension.Flamingo Theme Application||anchor="HUsingthemevariables"]])
36 * test your code all the [[supported browsers>>doc:Community.SupportStrategy.BrowserSupportStrategy]]
37 * 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
39 The following recommendations could be followed:
40
41 * Properties:
42 ** alphabetical order
43 ** 2 spaces indentation
44 ** put a space between selector and declaration start, ex. "##a {}##"
45 ** put a space before the property value, ex. "background-color: @dropdown-bg;"
46 ** use CSS shorthands
47 ** use relative sizes (em, %) instead of fixed ones (px)
48 ** IE hacks must be removed when updating existing code (since we do not support it anymore)
49 ** Avoid using {{code language="css"}}display: contents{{/code}}.
50 * Organization:
51 ** comment headers for separation and grouping of different parts of the code
52 ** Separate adjacent rulesets with an empty line.
53 * Overwriting:
54 ** document the localization of the overwrite using "Overwrites" and "Should be in" comments
55
56 == Comments ==
57
58 **Short comments** (less then 120 characters):
59
60 {{code language="css"}}
61 /* This is a short comment. */
62 {{/code}}
63
64 **Long comments**:
65
66 {{code language="css"}}
67 /* This is a very long comment that wraps
68 on multiple lines ...
69 and so on. */
70 {{/code}}
71
72 **Sectionning**:
73
74 This style should be used to declare sub-sections on a CSS file.
75
76 {{code language="css"}}
77 /**
78 * Section title.
79 */
80 {{/code}}
81
82 == Tools ==
83
84 * [[Firebug>>http://getfirebug.com/]]
85 * [[CSS Optimizer>>http://www.cssoptimiser.com/]] and [[CSS Compressor>>http://www.csscompressor.com/]] are two excellent online tools that can shrink CSS
86
87 = Testing =
88
89 See the [[Community.Testing]].

Get Connected