Manual:Coding conventions/SVG

From MediaWiki.org
Jump to navigation Jump to search

This page describes the coding conventions used within files of the MediaWiki codebase written in SVG. See also the general conventions that apply to all programming & markup languages, including SVG.

On per-project base we make use of SVGO as optimisation tool, see automated optimisation below. Another helpful tool for further manual optimisation is SVGOMG. It provides a visual before/after comparison.

Code structure [edit]

Minimal code as possible with readability in mind is the premise.

Example for simple optimised file – subtract.svg from OOUI:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
	<path d="M18 13H6v-2h12"/>
</svg>

Example for slightly more complex, optimised file – BetaFeatures screenshot template:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="264" height="162" viewBox="0 0 264 162">
    <title>
        BetaFeatures screenshot template
    </title>
    <defs>
        <clipPath id="jagged-edge">
            <path d="M0 0v152l12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10V0z"/>
        </clipPath>
    </defs>
    <g fill="#eaecf0" clip-path="url(#jagged-edge)">
        <path id="background" fill="#fff" d="M0 0h264v162H0"/>
        <path id="logo" d="M11 22c0-8 6-14 14-14s14 6 14 14-6 14-14 14-14-6-14-14M38 45v-5H13v5h25"/>
        <path id="sidebar" d="M38 163V58H13v106h25"/>
        <path id="personal-tools" d="M233 5h26v6h-26V5zM209 5h22v6h-22zM185 5h22v6h-22zM162 5h13v6h-13zM177 5h6v6h-6zM154 5h6v6h-6z"/>
        <path id="search-input" d="M258 16v4h-92v-4h92m1-1h-94v6h94v-6z"/>
        <path id="search-icon" d="M168 17h2v2h-2z"/>
        <path id="article" d="M252 162V29H48v133z"/>
        <path id="border" d="M0 0v162h264V0zm1 1h262v150.533l-11 9.166-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-11-9z"/>
    </g>
</svg>

We will explain the different coding conventions in the following section.

Automated optimisation (SVGO)[edit]

A standards set of conventions can be enforced by help of SVGO. If your original SVGs are well-formed, you should be able to automatically optimise them. As some SVGO v1.x plugins (options) might result in unexpected appearance with more complex SVGs, we differentiate between safe, considerably less-safe and unsafe plugins. With latter it's recommended to involve per-file quality assurance.

Safe plugins:

Mentioning only plugins, that are changed from default setting or that might be counter-intuitive:

  • Sorting attributes ('sortAttrs' – set to enabled; disabled by default)
  • Remove DOCTYPE ('removeDoctype' – using a DOCTYPE in SVGs is considered harmful by SVG standards authors as of SVG 2 Working Draft; enabled by default)
  • Remove or cleanup enable-background attribute when possible ('cleanupEnableBackground' – deprecated attribute, only supported by IE/Edge; enabled by default)

See SVGO Readme for other enabled, safe plugins.

Plugins to consider carefully: 

  • Round/rewrite number lists ('convertPathData' – can cause imprecise rendering; enabled by default)
  • Remove unused and minify used IDs ('cleanupIDs' – might negatively affect readability in more complex SVGs; enabled by default)
  • Remove raster images ('removeRasterImages' – as general rule dangerous; disabled by default)

Unsafe rules to disable (don't use!):

  • Remove XML processing instructions, aka XML declaration <?xml version="1.0" encoding="UTF-8"?> ('removeXMLProcInst' – issues when viewed as standalone file in some editors, also possible issues with MIME type interpretation; enabled by default)
  • Remove <title> ('removeTitle' – problematic for accessibility reasons; enabled by default)
  • Remove <desc> ('removeDesc' – problematic for accessibility reasons; enabled by default)
  • Remove viewBox attribute ('removeViewBox' – results in troublesome appearance in some browsers, therefore both, width/height and viewbox should be featured; enabled by default)
  • Remove dimensions width/height when viewbox is available ('removeDimensions' – as above; disabled by default anyways)

Exemplified safe configuration:[edit]

$ svgo path/to/image.svg --disable={cleanupIDs,convertPathData,removeDesc,removeTitle,removeViewBox,removeXMLProcInst} --enable='sortAttrs' --pretty

Manual optimisation[edit]

Beyond automated optimising SVGs there are further steps to consider:

  • Remove standalone="no" from XML processing instruction, as it's default
  • Lowercase (for better gzipping) and shorten hex color values – #fff over #FFFFFF
  • Merging paths <p> where applicable
  • Paths are preferable over certain SVG shapes like <rect> or <circle>

If you want to dig even deeper, there are more more optimisations to compress delivery, such as:

  • auto-closing paths (aka removing z for certain shapes),
  • use relative commands when creating paths (instead absolute commands, e.g. "m" for "move by", instead of "M" for "move to"),
  • optimising for compression backreferences

that might save some extra bytes depending on what it's worth.