Wiki source code of HTML & CSS Code Style
Last modified by Lucas Charpentier (Sereza7) on 2024/03/25 11:16
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). | ||
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]]. |