Wiki source code of HTML & CSS Code Style
Last modified by Lucas Charpentier (Sereza7) on 2024/04/02 11:29
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 | ||
15.1 | 16 | The XWiki project is following the [[W3C WCAG 2.1 Guidelines>>https://www.w3.org/TR/WCAG21/]] (level AA). | |
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/]] | ||
4.1 | 33 | * don't use ##!important## declarations | |
3.1 | 34 | * don't use inline style declarations | |
32.1 | 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"]]) | |
35.1 | 36 | * 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 | 37 | * test your code all the [[supported browsers>>doc:Community.SupportStrategy.BrowserSupportStrategy]] | |
14.1 | 38 | * 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 | |
3.1 | 39 | ||
40 | The following recommendations could be followed: | ||
3.3 | 41 | ||
3.2 | 42 | * Properties: | |
3.3 | 43 | ** alphabetical order | |
44 | ** 2 spaces indentation | ||
8.1 | 45 | ** put a space between selector and declaration start, ex. "##a {}##" | |
31.1 | 46 | ** put a space before the property value, ex. "background-color: @dropdown-bg;" | |
47 | ** use CSS shorthands | ||
3.3 | 48 | ** use relative sizes (em, %) instead of fixed ones (px) | |
16.1 | 49 | ** IE hacks must be removed when updating existing code (since we do not support it anymore) | |
18.1 | 50 | ** Avoid using {{code language="css"}}display: contents{{/code}}. | |
3.1 | 51 | * Organization: | |
3.3 | 52 | ** comment headers for separation and grouping of different parts of the code | |
24.1 | 53 | ** Separate adjacent rulesets with an empty line. | |
3.1 | 54 | * Overwriting: | |
3.3 | 55 | ** document the localization of the overwrite using "Overwrites" and "Should be in" comments | |
3.1 | 56 | ||
10.4 | 57 | == Comments == | |
58 | |||
11.2 | 59 | **Short comments** (less then 120 characters): | |
10.4 | 60 | ||
61 | {{code language="css"}} | ||
62 | /* This is a short comment. */ | ||
63 | {{/code}} | ||
64 | |||
11.2 | 65 | **Long comments**: | |
10.4 | 66 | ||
67 | {{code language="css"}} | ||
68 | /* This is a very long comment that wraps | ||
69 | on multiple lines ... | ||
70 | and so on. */ | ||
71 | {{/code}} | ||
72 | |||
11.2 | 73 | **Sectionning**: | |
10.4 | 74 | ||
75 | This style should be used to declare sub-sections on a CSS file. | ||
76 | |||
77 | {{code language="css"}} | ||
78 | /** | ||
79 | * Section title. | ||
80 | */ | ||
81 | {{/code}} | ||
82 | |||
5.1 | 83 | == Tools == | |
3.1 | 84 | ||
3.3 | 85 | * [[Firebug>>http://getfirebug.com/]] | |
3.1 | 86 | * [[CSS Optimizer>>http://www.cssoptimiser.com/]] and [[CSS Compressor>>http://www.csscompressor.com/]] are two excellent online tools that can shrink CSS | |
87 | |||
1.1 | 88 | = Testing = | |
89 | |||
12.2 | 90 | See the [[Community.Testing]]. |