svg_guidelines.rst (12746B)
1 SVG Guidelines 2 ============== 3 4 Pros and cons of SVG for images 5 ------------------------------- 6 7 When used as a document format there is usually a compelling reason that 8 makes SVG the only solution. When used as an `image 9 format <https://developer.mozilla.org/en-US/docs/Web/SVG/SVG_as_an_Image>`__, 10 it is sometimes less obvious whether it would be best to use SVG or a 11 raster image format for any given image. The vector format SVG and 12 raster formats like PNG both have their place. When choosing whether or 13 not to use SVG it is best to understand the advantages and disadvantages 14 of both. 15 16 File size 17 Whether SVG or a raster format will produce a smaller file for a 18 given image depends very much on the image. For example, consider an 19 image of a path with a gradient fill. The size of an SVG of this 20 image will be the same regardless of the dimensions of the image. On 21 the other hand the size of a raster file of the same image will 22 likely vary tremendously depending on the dimensions of the image 23 since the larger the dimensions the more pixel data the file needs to 24 store. At very small dimensions (the extreme case being 1px x 1px) 25 the raster file will likely be much smaller than the SVG file since 26 it only needs to store one pixel of data. At large dimensions the 27 raster file may be much larger than the SVG file. 28 Scalability, with caveats 29 One of the primary advantages of SVG is that as it is scaled it does 30 not pixelate. However, this is not to say that it always does away 31 with the need to have a collection of raster images for display at 32 different scales. This can be particularly true for icons. While SVG 33 may scale well enough for flat-ish icons without a lot of detail, for 34 icons that try to pack in a lot of detail graphic artists generally 35 `want to be able to pixel 36 tweak <https://www.pushing-pixels.org/2011/11/04/about-those-vector-icons.html>`__. 37 Performance 38 While SVG provides a lot of flexibility in terms of scaling, 39 themability, etc. this flexibility depends on doing computations for 40 SVG images at the time they're displayed, rather than at the time the 41 author creates them. Consider an image that involves some complex 42 gradients and filters. If saved as a raster image then the work to 43 rasterize the gradients and filters takes place on the authors 44 computer before the result is stored in the raster file. This work 45 doesn't need to be redone when the image is displayed on someone 46 else's computer. On the other hand, if the image is saved as an SVG 47 image then all this work needs to be done each time the SVG is 48 displayed on someone else's computer. This isn't to say that SVG 49 images are always slower than raster equivalents. In fact it can be 50 faster to send vector information from an SVG to a user's GPU than it 51 is to extract raster data from an equivalent raster image. And even 52 when an SVG image is slower than a raster equivalent, the difference 53 is usually not noticeable. However, just don't fall into the trap of 54 thinking that SVGs are faster than equivalent raster images, or vice 55 versa. Once again, "it depends". 56 57 Authoring guidelines 58 -------------------- 59 60 A lot of SVG files (particularly those generated by SVG editors) ship 61 without being cleaned up and can contain a ton of junk that bloats the 62 file size and slows down rendering. In general the best way to combat 63 this is to first run SVG files through a linter such as 64 `svgo <https://github.com/svg/svgo>`__ (see the Tools section below). 65 However, when authoring SVGs by hand here are some best practices to 66 help keep them lightweight. These rules are based on some real examples 67 seen in Mozilla's code. 68 69 Basics 70 ~~~~~~ 71 72 - Two spaces indenting 73 - No useless whitespaces or line breaks (see below for more details) 74 - Adding a license header 75 - Use double quotes 76 77 Whitespace and line breaks 78 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 79 80 Whitespace 81 ^^^^^^^^^^ 82 83 In addition to trailing whitespace at the end of lines, there are a few 84 more cases more specific to SVGs: 85 86 - Trailing whitespaces in attribute values (usually seen in path 87 definitions) 88 - Excessive whitespace in path or polygon points definition 89 90 Whitespace examples 91 ^^^^^^^^^^^^^^^^^^^ 92 93 This path: 94 95 .. code:: html 96 97 <path d=" M5,5 L1,1z "> 98 99 can be cut down to this: 100 101 .. code:: html 102 103 <path d="M5,5 L1,1z"> 104 105 Similarly, this polygon: 106 107 .. code:: html 108 109 <polygon points=" 0,0 4,4 4,0 "/> 110 111 can be cut down to this: 112 113 .. code:: html 114 115 <polygon points="0,0 4,4 4,0"/> 116 117 Line breaks 118 ^^^^^^^^^^^ 119 120 You should only use line breaks for logical separation or if they help 121 make the file readable. You should avoid line breaks between every 122 single element or within attribute values. It's recommended to put the 123 attributes on the same line as their tag names, if possible. You should 124 also put the shortest attributes first, so they are easier to spot. 125 126 Unused tags and attributes 127 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 128 129 Editor metadata 130 ^^^^^^^^^^^^^^^ 131 132 Vector editors (Inkscape, Adobe Illustrator, Sketch) usually add a bunch 133 of metadata in SVG files while saving them. Metadata can mean many 134 things, including: 135 136 - The typical "Created with *editor*" comments 137 - Non-standard editor specific tags and attributes (``sketch:foo``, 138 ``illustrator:foo``, ``sopodi:foo``, …) 139 - The `XML 140 namespace <https://developer.mozilla.org/en-US/docs/Web/SVG/Namespaces_Crash_Course>`__ 141 definition that comes with the latter (``xmlns:sketch``, 142 ``xmlns:sopodi``, …) 143 144 Other metadata 145 ^^^^^^^^^^^^^^ 146 147 In addition to non-standard editor metadata, standard compliant metadata 148 also exists. Typical examples of this are ``<title>`` and ``<desc>`` 149 tags. Although this kind of data is supported by the browser, it can 150 only be displayed when the SVG is opened in a new tab. Plus, in most of 151 the cases, the filename is quite descriptive So it's recommended to 152 remove that kind of metadata since it doesn't bring much value. 153 154 You shouldn't include DOCTYPEs in your SVGs either; they are a source of 155 many issues, and the SVG WG recommends not to include them. See `SVG 156 Authoring 157 guidelines <https://jwatt.org/svg/authoring/#doctype-declaration>`__. 158 159 Avoid the use of CDATA sections 160 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 161 162 `CDATA 163 sections <https://developer.mozilla.org/en-US/docs/Web/API/CDATASection>`__ 164 are used to avoid parsing some text as HTML. Most of time, CDATA isn't 165 needed, for example, the content in ``<style>`` tags doesn't need to be 166 wrapped in a CDATA section as the content inside the tag is already 167 correctly parsed as CSS. 168 169 Invisible shapes 170 ^^^^^^^^^^^^^^^^ 171 172 There are two kinds of invisible shapes: The off-screen ones and the 173 uncolored ones. 174 175 The offscreen shapes are hard to spot, even with an automated tool, and 176 are usually context aware. Those kinds of shapes are visible but off the 177 `SVG view 178 box <https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox>`__. 179 Here's `an 180 example <https://hg.mozilla.org/mozilla-central/diff/9fb143f3b36a/browser/themes/shared/heartbeat-star-lit.svg>`__ 181 of a file with offscreen shapes. 182 183 On the other hand, the uncolored ones are easier to spot, since they 184 usually come with styles making them invisible. They must meet two 185 conditions: they must be devoid of any fill (or a transparent one) or 186 stroke. 187 188 Unused attributes on root ``<svg>`` element 189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 190 191 The root ``<svg>`` element can also host many useless attributes. Here's 192 an 193 `example <https://hg.mozilla.org/mozilla-central/diff/2d38fecce226/browser/components/loop/content/shared/img/icons-10x10.svg>`__ 194 taking into account the list below: 195 196 - ``version`` 197 - ``x="0"`` and ``y="0"`` 198 - ``enable-background`` (unsupported by Gecko and now deprecated by the 199 Filter Effects specification) 200 - ``id`` (id on root element has no effect) 201 - ``xmlns:xlink`` attribute when there are no ``xlink:href`` attributes 202 used throughout the file 203 - Other unused `XML 204 Namespace <https://developer.mozilla.org/en-US/docs/Web/SVG/Namespaces_Crash_Course>`__ 205 definitions 206 - ``xml:space`` when there is no text used in the file 207 208 Other 209 ^^^^^ 210 211 - Empty tags, this may be obvious, but those are sometimes found in 212 SVGs 213 - Unreferenced ids (usually on gradient stops, but also on shapes or 214 paths) 215 - ``clip-rule`` attribute when the element *is not* a descendant of a 216 ``<clipPath>`` 217 - ``fill-rule`` attribute when the element *is* a descendant of a 218 ``<clipPath>`` 219 - Unreferenced/Unused clip paths, masks or defs 220 (`example <https://hg.mozilla.org/mozilla-central/diff/2d38fecce226/toolkit/themes/shared/reader/RM-Plus-24x24.svg>`__) 221 222 Styling 223 ~~~~~~~ 224 225 Styling basics 226 ^^^^^^^^^^^^^^ 227 228 - Privilege short lowercase hex for colors 229 - Don't use excessive precision for numeric values (usually comes from 230 illustrator) 231 - Use descriptive IDs 232 - Avoid inline styles and use class names or SVG attributes 233 234 Styling examples 235 '''''''''''''''' 236 237 Here are some examples for excessive number precision: 238 239 - 5.000000e-02 → 0.05 (as seen 240 `here <https://hg.mozilla.org/mozilla-central/diff/2d38fecce226/browser/themes/shared/devtools/images/tool-network.svg#l1.31>`__) 241 - -3.728928e-10 → 0 (as seen 242 `here <https://hg.mozilla.org/mozilla-central/diff/2d38fecce226/browser/themes/shared/aboutNetError_alert.svg#l1.12>`__) 243 - translate(0.000000, -1.000000) → translate(0, -1) (as seen 244 `here <https://hg.mozilla.org/mozilla-central/diff/2d38fecce226/browser/themes/shared/heartbeat-icon.svg#l1.13>`__) 245 246 As for descriptive IDs: 247 248 - For gradients: SVG_ID1 → gradient1 (as seen 249 `here <https://hg.mozilla.org/mozilla-central/diff/2d38fecce226/browser/themes/shared/aboutNetError_alert.svg#l1.12>`__) 250 251 Use of class names 252 ^^^^^^^^^^^^^^^^^^ 253 254 - Avoid using a class if that class is only used once in the file 255 - If that class only sets a fill or a stroke, it's better to set the 256 fill/stroke directly on the actual shape, instead of introducing a 257 class just for that shape. You can also use SVG grouping to avoid 258 duplicating those attributes 259 - Avoid introducing variants of the same file (color/style variants), 260 and use sprites instead (with class names) 261 262 Default style values 263 ^^^^^^^^^^^^^^^^^^^^ 264 265 There's usually no need to set the default style value unless you're 266 overriding a style. Here are some commonly seen examples: 267 268 - ``style="display: none;"`` on ``<defs>`` elements (a ``<defs>`` 269 element is hidden by default) 270 - ``type="text/css"`` on ``<style>`` elements 271 - ``stroke: none`` or ``stroke-width: 0`` 272 273 SVG grouping 274 ~~~~~~~~~~~~ 275 276 Style grouping 277 ^^^^^^^^^^^^^^ 278 279 Group similarly styled shapes under one ``<g>`` tag; this avoids having 280 to set the same class/styles on many shapes. 281 282 Avoid excessive grouping 283 ^^^^^^^^^^^^^^^^^^^^^^^^ 284 285 Editors can sometimes do excessive grouping while exporting SVGs. This 286 is due to the way editors work. 287 288 Nested groups 289 ''''''''''''' 290 291 Avoid multiple-level nesting of groups, these make the SVG less 292 readable. 293 294 Nested transforms 295 ''''''''''''''''' 296 297 Some editors use ``<g>`` tags to do nested transforms, which is usually 298 not needed. You can avoid this by doing basic algebra, for example: 299 300 .. code:: xml 301 302 <g transform="translate(-62, -310)"><shape transform="translate(60, 308)"/></g> 303 304 can be cut down to: 305 306 .. code:: xml 307 308 <shape transform="translate(-2,-2)"/> 309 310 because: -62+60 = -310+308 = -2 311 312 Performance tips 313 ~~~~~~~~~~~~~~~~ 314 315 These rules are optional, but they help speeding up the SVG. 316 317 - Avoid using a ``<use>`` tag when that ``<use>`` tag is being 318 referenced only once in the whole file. 319 - Instead of using CSS/SVG 320 `transforms <https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform>`__, 321 apply directly the transform on the path/shape definition. 322 323 Tools 324 ~~~~~ 325 326 Tools can help to clean SVG files. Note, however that some of the rules 327 stated above can be hard to detect with automated tools since they 328 require too much context-awareness. To this date, there doesn't seem to 329 be a tool that handles all of the above. However, there are some 330 utilities that cover parts of this document: 331 332 - Mostly complete command line tool: https://github.com/svg/svgo 333 - Alternatives to SVGO: 334 335 - https://github.com/RazrFalcon/svgcleaner 336 - https://github.com/scour-project/scour 337 338 - GUI for command line tool (use with "Prettify code" and "Remove 339 ``<title>``" options on): https://jakearchibald.github.io/svgomg/ 340 - Good alternative to SVGO/SVGOMG: 341 https://petercollingridge.appspot.com/svg-editor 342 - Fixes the excessive number precision: 343 https://simon.html5.org/tools/js/svg-optimizer/ 344 - Converts inline styles to SVG 345 attributes: https://www.w3.org/wiki/SvgTidy 346 - RaphaelJS has a couple of utilities that may be useful: 347 `raphael.js <https://dmitrybaranovskiy.github.io/raphael/>`__