SVG is a generalized graphics markup language, which can be used for any purpose from icons to complex images to data visualizations to animated pictures to interactive applications. SVG can be generated by script libraries, by GUI drawing applications, or by hand-coding. Because of this flexibility, SVG does not dictate a structured content model, though it does provide primitives for structure, which can lead to suboptimal reusability, performance, and efficiency of SVG files, or poor interoperability between different authoring systems. This document describes some best practices for creating interoperability, reusable, performant, efficient, and practical SVG documents, using explanations and code samples.

Introduction

This document provides informative guidance (but does not set requirements) for authoring SVG. It is intended for use by developers creating SVGs by hand, or for implementers making applications or scripts that output SVG.

Specifically, this document demonstrates practical techniques for making SVG documents that you can easily:

This guide describes general techniques that are applicable across different use cases, including document structure, document order, navigation, and text and text alternatives. It also describes some techniques are unique to specific use cases, such as icons, complex images, data visualizations, animated pictures, interactive applications, or text-heavy images, each with their own optimization.

Definitions

screenreader:
A screenreader is an assistive technology user agent that identifies, interprets, and transforms the content of the document or webapp into a form that is more easily consumable for its user. Typically, a screenreader converts the content into text-to-speech, Braille output devices, or sound icons for use by people who are blind, visually impaired, illiterate, or learning disabled. Screenreaders are usually controlled through keyboard access, such as serial tab navigation and keyboard shortcuts, and sometimes used in combination with other assistive technology such as screen magnifiers.
replaced element
An HTML replaced element is an element which has its content replaced by an external source. Replaced elements include img, object, iframe, and video. Replaced elements have a default predetermined width of 300px and height of 150px.

General Techniques

These techniques are applicable across many different use cases for SVG.

Structure

There are two main aspects to the structure of an SVG document: the composition of shapes; and grouping and nesting.

Shape Composition

When creating an SVG, consider each individual shape for its function rather than just its initial appearance. Functional shapes can be styled, modified, and have new behavior added to them after the drawing is done.

In the following example, clock-bad-0.svg, the author has created a clock icon, which may appear satisfactory:


           

          

However, rather than simply using the stroke of the shape, the author defined the inner and outer sides of the line shape, meaning that you can't independently style the clock face (the shape's fill or "background") and the outline, as shown in the following example, clock-bad-0a.svg, where we would expect to be able to make the clock face yellow:


           

          

Changing the fill only changes the color of the shape outline, not the shape background. Also, frequently for icons, you'd like to be able to increase or decrease the stroke width for different image sizes, and this type of path-outline shape doesn't let you do that; the minimum thickness of the shape outline is fixed unless you change the geometry of the path.

Besides the styling problems, using shape outlines dramatically increases the file size, usually much more than double the size. Sometimes this shape-outline technique is useful and necessary, especially when you want to simulate variable stroke widths, like a calligraphic stroke, but for uniform stroke widths, this is unnecessary and even a disadvantage.

Authoring Tool Tip: In Adobe Illustrator, this feature is called Outline Stroke (an option under Object > Path). It's easy to convert a stroke to an outline, but there is no easy way to convert an outline to a stroke. Thus, authors are encouraged not to use Outline Stroke unless required.

We can start to fix these problems by defining the shape as a simple stroke, which allows the stroke and fill to be styled seperately, as in the following example, clock-bad-1.svg:


           

          

Still, both the clock face and the hands are composed of a single path element. This means that if you decide to change any of the styling, such as the color of the stroke or the fill, or width of the stroke, you cannot change only the clock face or hands, but must change both together. And even more obvious, the fill has an artifact where the hands make a blank space.

We can fix that by splitting the clock face and hands into two separate shapes (now a circle and a path element), which allows individual styling, as in the following example, clock-bad-2.svg:


           

          

However, there is still a problem, because the individual hands are a single element, which doesn't let them be styled differently (among other problems we'll describe next). We split the clock hands into two separate shapes, which allows individual styling, as in the following example, clock-bad-3.svg:


           

          

This is an improvement, and now allows individual image components not only to be styled differently, but also replaced independently much more easily, such as making a more elaborate hour hand with a simple minute hand. In addition, we've added another functional aspect to the clock hands. An author could (and should) anticipate that someone (whether the developer on their team, a stranger reusing their image with permission, or themselves at some later point) would want to animate the clock hands. The following example, clock-animate-0.svg, shows that adding a simple rotation animation is now easy:


           

          

Another small improvement will make this even more robust. By changing the origin of the individual hands from the end points to the center points, we ensure that additional transforms do not disrupt the hand animation, as in the following example, clock-animate-1.svg:


           

          

In addition to animation, other functional aspects of a shape are various kinds of interactivity, such as clicking or mouseovers.

By thinking about a shape's possible functions and behaviors, and not only its appearance, an author can make their SVG more reusable from the beginning.

Grouping and Nesting

In SVG, you can organize your images into logically related items using the g (“group”) element. For example, if you have an image of a family standing under a tree, next to their car, in front of their house, where each object is made up of several components, you can group together each object, and even groups of objects; you can have one group for the tree and its branches and leaves, one group for the house and its doors and windows, one group for the car and its windows and tires, and one group for all the people, with a nest group for each person and their heads, bodies, limbs, and clothes.

For authors, grouping related items makes it easier to maintain and to style common objects, to nest sets of groups, to select and reorder collected objects, and to hide and show groups individually. For users, grouping helps navigation, especially for use through a keyboard or a screenreader.

Authoring Tool Tip: In Adobe Illustrator and some other authoring tools, the g element corresponds to a layer. Each layer is a separate group, and the contents of the layer are the contents of the group.

TODO: add group example, nested groups

TODO: add group styling example

TODO: add group ID example

Document Order

An author should make sure that the SVG document has a document order that mirrors the intended reading order for the content, including any “hidden” text.

SVG uses absolute positioning and a painter's model for rendering graphical and textual content.

SVG's absolute positioning layout means that each element is positioned precisely by its geometric (e.g. x,y) description, and that this position is not affected by any other element; this is unlike the common case in CSS, where adding content “pushes” the content after it in document order to a new position. SVG's absolute positioning is shown in the following example, absolute-positioning.svg, in which the group with the blue circle (labeled 1) is before the gold square (labeled 2) in document order, but is positioned to the right of it in rendering order:


         

        

The painter's model means that the first element in the document is rendered first, the second element is rendered next, and so on, with each element that overlaps a previous element being drawn “on top” of that previous element, like the following example, painters-model.svg, in which the first element, a yellow square, is overlaid by the second element, a blue circle, which in turn is overlaid by the third element, a green line (hovering over each element will show the element below):


         

        

The combination of absolute positioning and painter's model lead to a circumstance where it is relatively easy for authors to inadvertently misorder the reading flow of a document. This risk is increased when the “invisible metadata” of the title and desc elements is added to the document, since it is easy for authors to overlook how the sequence of “hidden” text will flow with any visible text, or flow between multiple sets of “hidden” text.

A bad document reading order is illustrated in this example, document-order-bad.svg:


         

        

Though it is rendered in a logical order, the document reading order is #2, then #4, then #1, then #3, then the names of the fruits. This is corrected in the following example, document-order-good.svg, in which the reading order and the rendering order are aligned:


         

        

A simple way to check the reading order of the document is to “select all” in your SVG document in the browser, and paste it into a text file. If the resulting text makes sense in this text file, then then reading order of your SVG document is acceptable. Note that not all browsers include titles in a selection, so account for them separately.

Text and Text Equivalents

Unlike text in a raster image, which is simply pixels and shapes, text content in SVG can be included directly with the text element. This text content is machine–readable, indexable and searchable by search engines, findable though “find text” functionality, selectable with the keyboard or mouse, and translatable. As in HTML, SVG text can be styled (including different styles for fill and the stroke) and can use Web fonts (such as WOFF, TTF, and OTF formats).

The textPath element even permits text to run along the stroke of an SVG shape, something not possible in HTML alone, as in this example, textpath.svg:


         

        

Additionally, text is convenient for authoring, because it can be changed quickly and easily. The words themselves can be changed with little effort, and Web fonts afford a wide variety of styles that can substitute for logos or other stylized text.

Wherever possible, text in SVG should be actual textual content, and not simply elements shaped like text, because you lose all the benefits of text.

On a related note, authors should consider placing important, contextual, or navigation items first in the document order.

Text Equivalents

Sometimes, text is not enough for a particular use, either because the shapes can't be represented in a font (such as with custom-drawn interlocking words), or because the SVG image is graphical rather than textual.

In this case, the author should use the title and desc elements to provide text equivalents for all elements that are important for the user to understand the image.

The title element

The title element, when included as the first child of an element, lets the author provide a short, meaningful title for that element, similar to the alt attribute in HTML.

For example, if an SVG document contains an image of an apple that is important to the understanding of the document, the author should include a title element with the word “Apple”, like so:

<path d="…">
  <title>Apple</title>
</path>
        

Screenreaders should treat the content of the title element as the “accessible name” in the accessibility tree. Unfortunately, due to inconsistencies in current browsers and screenreaders, the title element is not yet consistently supported, so for now if you want your SVG to be accessible you also need to give the title an id attribute, and point to it with the aria-labelledby attribute, as in this example, title.svg:


          

        

Similar to HTML, you can give the entire document a title by using a title as the first child element of the root svg element, as show in the last example. You should always give your SVG document a title in this way.

Most of the examples in this document don't include a root title element, for the sake of simplicity and clarity of the specific technique, but this should be an exception.

Whenever possible, authors should use a visible text element to provide a label, for affordance for all users. Authors must not duplicate the text of a text element in a related title element, since that will be distracting, confusing, annoying, and counterproductive for screenreader users.

Browsers typically provide a tooltip (an information popup) when elements with a title are hovered over. Authors should resist the temptation to use this as a means to provide instructions for use, but should only use the title element to give a meaningful title to that element. Otherwise, users of screenreaders will have no context for the instructions.

The desc element

The desc element, when included as a child of an element, lets the author provide a longer description, when necessary, to supplement the title for that element. The desc element should be used sparingly.

For example, if an SVG document contains an image of an apple that is important to the understanding of the document, and the title alone might not convey the whole context, the author may include a desc element to supplement a title, like so:

<path d="…">
  <title>Apple</title>
  <desc>A large Granny Smith apple with a bite taken out of it, 
    sitting on the grass.</desc>
</path>
        

Screenreaders will treat the content of the desc element as a supplementary description in the accessibility tree, available on request.

TODO: title and desc, title for document and group

Accessibility Tip: .

Navigation and Activation

Many users navigate Web documents, including SVG documents, via the keyboard. This may be a serial navigation via the tab key, through keyboard shortcuts, activating links and interactive elements via the enter/return key, or various other means. Other users have navigation challenges by using touch-screens, often with a small surface (such as smart phones), and no way to distinguish between "hovering" and "clicking". Still other users have unsteady hands or limited mobility, and must navigate slowly or through single-switch controls.

Users of screenreaders or screen magnifiers may have difficulty locating navigable or activatable elements.

In order to meet the needs of these users, if an element is important, navigable, or activatable, it must have an indication in the markup that it can receive focus control.

The a and text elements are focusable by default.

All other elements, if they are to be focusable, must be have a tabindex attribute, with a positive value; generally, the value should be 0. SVG also includes a focusable attribute and property, but this is not well supported across browsers, and tabindex should be preferred for now.

In addition to being focusable, authors should make sure interactive elements are large enough for selection and activation by small-device users and users with unsteady hands.

TODO: add navigation example

Resizability

Many SVG images are defined to be of fixed dimensions, such as 150 pixels wide and 50 pixels high, just like raster images like JPEG or PNG format. However, the more common use case for SVG is to automatically resize to fit the available space. Raster images have intrinsic sizes and dimensions because they are composed of a fixed set of rows of pixels, and the appearance of those pixels would be distorted if displayed at a larger or smaller size, producing artifacts called pixelization. By contrast, SVG images are drawing instructions for an image that are equally crisp at any size, called vectors, a characteristic called scalability (thus the name Scalable Vector Graphics). The fixed-size output of many SVG generators is not optimized for use on the Web, where different devices have variably-sized screens, and where an SVG image may be referenced in an HTML file at different sizes than the original dimensions.

It's simple to take advantage of SVG's native scalability, while still defining the abstract native dimensions of the image. The SVG root element has three attributes to control these characteristics: the width; height; and viewBox attributes.

The width and height attributes

The width and height attributes respectively specify the horizontal and vertical dimensions of the image. The attribute values may have units, such as pixels (150px) or centimeters (7cm), or they may omit units dimensions and be interpreted abstractly in user units, e.g. relative dimensions that scale to the size of the container.

The viewBox attribute

The viewBox attribute sets the viewport of the SVG via 4 space-separated numbers, in the form "x y width height".

An SVG image has an infinite canvas, with the 0,0 origin at the top-left point, and positive values moving down and to the right (i.e. the fourth quadrant of a traditional Cartesian coordinate space); a graphical element may be located at any point in this space, whether at a positive or negative x or y. The viewBox attribute controls which section of this infinite canvas is visible in the viewport.

For example, the following code sample shows an SVG root element that has a viewport that starts at 0,0, and has a width of 100 units and a height of 50 units:

<svg viewBox="0 0 100 50">
        

This means that any graphical shape that is contained (fully or partially) within that space will be visible in the viewport (at least partially, based on the position and overlap).

To extend this example, the following code sample shows the same viewBox, and also includes a width and height:

<svg width="20" height="10" viewBox="0 0 100 50">
        

This will produce an SVG of a fixed size (20 pixels by 10 pixels) with a 2:1 dimension ratio, and a viewport that includes all elements that are within the confines of the viewport.

Setting the width and height attributes to 100% tells the browser to use the full available space of the container for the units. This means that the SVG will take up full width and height of the image (img) element in HTML, or the whole browser window if the SVG image is viewed as a stand-alone document.

<svg width="100%" height="100%" viewBox="0 0 150 70">
        

This is actually the default behavior for an SVG image that doesn't have explicit width and height attributes, so you can get the same effect by only using the viewBox attribute and omitting the width and height attributes:

<svg viewBox="0 0 150 70">
        

Because SVG is case-sensitive (a legacy of its XML origins), the attribute viewBox must have a capital “B”. It's a common mistake to type viewbox instead, which is easily overlooked and frustrates debugging. SVG uses a mix of attribute-name delimiters, including medial camelCase (“viewBox”), lower-case compound (“viewbox”), and kebab-case (“view-box”), so this is a common error. We're sorry about that.

We explore the viewBox attribute more in the section on Icons and Symbols.

Resizability Example

In this example, we show an auto-sizing SVG in an HTML object element at half-size, full-size, double-size, and triple-size, all referencing the same SVG document, auto-resizable.svg:


          
          
          
          

        

Note that although vector images have crisp borders and lines at all sizes, there are still perceivable differences at different sizes. For example, a curved corner may appear too rounded and text may appear too large if a small icon is displayed at a large size, or a complex image may appear more cluttered and hard to distinguish if displayed at a small size. Some of these vector artifacts may be reduced by changing styling or hiding or showing different elements at different sizes, using Media Queries as described in the section on Responsive Images.

Accessibility Tip: Making images auto-scaling can help users with low vision or mobility issues, since they can increase the size of the image to suit their needs, making it easier to see details or to click on interactive elements.

Fixed Sizes

Using fixed dimensions rather than auto-sizing does have some use cases, including specifying print sizes in real-world units, and seting intrinsic size for use in HTML when no sizing is defined in HTML or CSS (noting the width and height defaults of 300px by 150px for replaced elements in HTML). This differences between auto-sized and fixed-size SVGs are illustrated in these two examples, where no dimensions are specified in the object, with the first SVG using fixed dimensions (with intrisic width and height of 200px by 200px) and the second SVG using auto-sizing (with the default width and height of 300px by 150px):

SVG with fixed dimensions
SVG with auto-sizing

Responsive Images

A responsive image is one which adapts to best fit the display device's capabilities, whether different sizes, resolutions, orientation (e.g. portrait or landscape), or color ranges (e.g. color or grayscale). One approach to creating responsive images is to use a media query, which is a CSS mechanism that allows a document to have different style rules based on different media features, such as width, height, color, display orientation, and resolution. SVG's scalable nature makes styling things based on sizing a natural fit in particular, though other factors, such as orientation or color gamut are also useful with SVG.

For instance, some images look good at a large size, but at a small size the stroke-width becomes too thin and there isn't enough visual contrast, as in the following example, clock-non-responsive.svg, referenced at two different sizes via object elements:


          
          

        

While the stroke-width remains constant relative to the the other details of the image, such as the radius of the circle, it now appears too thin. To address this perception issue, you can use media queries to increase the stroke-width of an SVG icon when it's shown at small sizes, to enhance the visual contrast and make certain details more distinct. We illustrate this in the following example, clock-responsive-0.svg, referenced at two different sizes via object elements:


          
          

        

Building on this example further, sometimes at large sizes (or "close up" zoomed images) you want more detail, but at small sizes (or "further away"), these extra details simply clutter up the image, detracting from it rather than enhancing it. Adding and removing detail based on size (or "nearness") is known as "level of detail" or LOD. To achieve LOD in SVG with media queries, in addition to changing stroke-width, you can change other styling characteristics, such as fill (a more complex gradient versus a simple flat color versus high-contrast colors), markers (such as arrowheads on the end of a line), or simply toggling the visibility of particular parts of the image (such as showing numbers at large sizes, tick marks at smaller sizes, and nothing at all at very small sizes). The the following more complex example, clock-responsive-1.svg, we illustrate some of these techniques in the same SVG image at three different sizes:


          
          
          

        

Note that Media Queries may not work in all SVG authoring tools. For example, opening a responsive SVG in Adobe Illustrator or Inkscape may not display the expected results.

We explore the viewBox attribute more in the section on Resizability.

Animation

.

TODO: talk about distraction, epilepsy, and slow movement

SVG in HTML

There are 5 main ways to use SVG in HTML content: inclusion in inline markup; referenced in the object element; referenced in the img element; referenced in the iframe element; or referenced as a CSS background.

Inline SVG in HTML results in a single hybrid HTML+SVG document. This has the advantages that the image is carried along with the document, so it can't be lost when moving the file around (the same advantage that inline CSS has over an external stylesheet), and that the SVG can share the same scripts and styles that are applied to the HTML content (that is, they share the same DOM).

All the other methods (linked by object, img, or iframe replaced elements or in CSS) assume an external SVG file, referenced like any other image format (such as PNG or JPEG). External SVGs have a few advantages, including the ability to easily swap out the image, to use the image in multiple files (taking advantage of caching), to use the image as a standalone SVG (that is, as an image outside any HTML), and to isolate the SVG DOM from HTML for easier scripting and styling or for security or privacy.

Inline SVG in HTML

Inline SVG in HTML .

The example inline-svg.html shows an inline SVG with styles applied from CSS in the HTML head:


          

          

It's not necessary in inline SVG to include the SVG and XLink namespace attributes. However, it is still necessary to include them in standalone SVG, so if an SVG file is intended for use both inline and standalone, it's a safe practice to include the SVG and XLink namespace attributes, in case an inline SVG is reused as a standalone file.

Script in Inline SVG in HTML

HTML5 specifies that the HTML external script element is not a self-closing element, unlike the SVG element of the same name, but also specifies that the SVG external script element in inline SVG should be parsed as normal for SVG. Thus, a self-closing external script element is valid, like so:

<svg>
  <script xlink:href="…"/>
</svg>
            

However, not all browsers parse this self-closing element correctly, and may not load and run the script, so it is safer in inline SVG to use a closing tags for the exernal script element, like this:

<svg>
  <script xlink:href="…"> </script>
</svg>
            

The example inline-svg-script.html shows an inline SVG with with both styles of external script element, which are theoretically the same but may differ in practice:


            

            

TODO: describe different behavior in onload and document in inline vs standalone

SVG in the object element

This example svg-in-object.html shows an external SVG referenced with the object element:


          

          

The object element is the preferred way to reference an external SVG. Using the object or iframe elements allow text search and selection, interactivity on a per-element level, and the execution of script, which aren't currently allowed using the img element. This is illustrated in these two examples, the first using <object> and the second using <img>

SVG in <object>, with animation, script, and full interactivity
SVG in <img>, with animation, but no script or interactivity

In comparison to the iframe element, the object element doesn't have a default border, and also scales to matches the intrinsic size and dimensions of the SVG content, while the iframe size is determined by styles in the HTML page. This is illustrated in these two examples, which have no CSS sizing defined:, the first using <object> and the second using <iframe> (which uses the default width and height of 300px by 150px for replaced elements in HTML):

SVG in <object>
SVG in <iframe>

The embed element is also a valid HTML5 element, which acts effectively the same as the object element. As with the iframe element, there are no advantages to using the embed element rather than the object element, so authors are encouraged to using object instead. Thus, this guide doesn't describe the embed element in any more detail.

SVG in the img element

The img element is another common way to reference an external SVG. The advantage of img is that many graphical authoring tools and environments support the insertion of img element, and may not support inserting the object element.

The img element allows animation, but does not enable text search and selection, interactivity on a per-element level, or the execution of script.

The example svg-in-img.html shows an external SVG referenced with the img element:


          

          

Note that not all browsers support animation in the img element, so the safest approach is to use inline SVG or the object element.

SVG in the iframe element

The iframe element is another way to reference an external SVG.

As with the object element, the iframe element allows text search and selection, interactivity on a per-element level, and the execution of script, which aren't currently possible with the img element. However, for SVG, there are no advantages to using the iframe element over the object element, and there are some disadvantages. As mentioned before, the iframe element has a border as the default style, which is not normally desirable, and the iframe size is determined by styles in the HTML page, rather than using the intrinsic size and dimensions of the SVG content. So, it's recommended to use object instead of iframe.

The example svg-in-iframe.html shows an external SVG referenced with the iframe element:


          
        

SVG as a CSS background

Another method to reference an external SVG in HTML is by specifying SVG as a background image in CSS, which can be applied to any HTML element.

As with the img element, SVG's used as a background image don't allow text search and selection, interactivity on a per-element level, or the execution of script.

The example svg-in-css-background.html shows an external SVG referenced as a CSS background image:


          
        

HTML in SVG

Sometimes, you may wish to include HTML in your SVG, such as structured text content like lists or form controls. The SVG foreignObject element lets you embed chunks of HTML directly into your SVG. You can include a whole HTML document, or just individual snippets of HTML. The most reliable content in a foreignObject element is a single HTML body element containing other HTML content, or one or more HTML flow content elements.

Because of SVG's XML origins, the HTML content should be well-formed XHTML, and you must use the HTML namespace declaration, xmlns="http://www.w3.org/1999/xhtml", in each HTML parent element in the foreignObject element. If you don't use the namespace declaration, the HTML content won't be rendered in current browsers.

For instance, in the following example, foreignObject-html-bad.svg, there is a list with 3 list items contained in a parent HTML ul element that has a namespace declaration that will render, and a paragraph that doesn't have namespace declaration that won't render:


         

        

The following example, foreignObject-html.svg, has two parent HTML elements in the foreignObject element, ul and select, and both have namespace declarations, so they'll both render correctly:


         


        

Accessibility Tip: Because modern screenreaders were designed to interface with HTML, using HTML in your SVG can often be a very effective way to make your structured content or interactive controls accessible.

Authoring Tool Tip: Most SVG authoring tools, and some other SVG graphics tools, don't support HTML, so they won't render any HTML in your SVG. Some may not accept even an SVG file containing HTML as valid. Some authoring tools may accept the file, but not include the HTML content when saving the file. Be sure to test your SVG tools for HTML support before relying on them.

As defined in the SVG specification, the foreignObject element is not limited to rendering HTML, but should be able to contain any arbitrary XML, such as MathML. In practice, modern browser support for any other content than HTML in the foreignObject element is unreliable.

ARIA: Semantic Markup Attributes

SVG is a semantically-neutral markup language, so you can add semantics by using ARIA markup attributes. HTML is a moderately semantic markup language, with elements that convey specific meaning about document structure (e.g. h2, section), Aside from a few functional semantic elements such as a, title, and desc and structural semantic elements like g and defs, SVG has none of these semantics or native controls and focuses solely on geometry, positioning, presentation, and implicit semantics such as document order and structure (including grouping and nesting). This means that SVG is a blank canvas to apply whatever semantics you wish to your elements. Unlike in HTML, there are very few native semantics to SVG, particularly around text or widget controls. If you want a well-structured document that ......

For instance, you can make SVG text explicitly considered to be a list, as in the following example, aria-list.svg, which uses ARIA to add a heading and a set of nested list items:


         

        

You can even create even more complex semantic structures like a table, as in the following example, aria-table.svg:


         

        

Note that you can very effectively style ARIA-decorated elements using the CSS attribute selector, similar to how you would style their semantic-element equivalents.

TODO: talk about ARIA

Specific Techniques

These techniques are considerations across different use cases.

Icons and Symbols

SVG does not have predefined symbols, unlike some earlier dedicated topic-specific graphics languages. Instead, SVG allows the author to create their own symbols with the symbol element. These symbols can be references with the use element, which is a way to clone elements.

The use element copies the visual rendering of whatever element it references, and you can change the position and sometimes the style of the referenced element for each use instance. The use element is not confined to referencing the symbol element, but can point to any graphical shape or even group of shapes, including a nested svg element. Thus, in practice, the symbol element functions much like a nested svg element, including its own viewBox attribute to establish the element's viewport.

Logical positioning

Often, when an SVG author uses a graphical authoring tool, they draw their image in the middle of the drawing canvas, and clip the canvas to the shape to remove extra whitespace for the final image. When you do this, you are inadvertently reducing the reusability of the SVG image. When someone else (or you at a later time) wants to extract individual components of your image, for stand-alone use or for composition into another SVG image, or wishes to animate individual components, the position of the image makes it difficult.

Underneath the hood, the authoring tool is usually setting a viewBox attribute with an origin other than 0,0, and sometimes is applying a clipPath element. Instead of clipping the image, move the entire image close to the top-left corner of the screen, and set the width and height (i.e. viewport) of the document to the size you want (including necessary padding).

Similarly, when a shape or a group of shapes has a transformation applied to it, these transformations can accumulate and make the individual components of your image hard to extract and to reuse in another context. Most authoring tools have a way to “apply” transformations directly to the shapes, changing the geometric characteristics of the elements, rather than keeping the transformations as SVG transform attributes.

Combined, these two techniques make SVG images more reusable, for yourself and others.

Accessibility Tip: Transformations applied to interactive elements often change only the visual appearance, and not the document order, for a shape. Be sure that all elements, whether they are textual or graphical, are in the logical order for serial navigation, not just a visual order.

Animation Tip: Accumulating and nested transformations makes additional transformation animations difficult to calculate for individual animations.

Centering Symbols

The use element lets you position icons and symbols, as in this example, use-element-1.svg:


            

          

However, you can see that the x,y position in the use element is still based on the top-left coordinates of the symbol being referenced, illustrated in this example, use-element-2.svg, where the red dot indicates the use element's x,y position:


            

          

This is often inconvenient for positioning elements, because if you want the symbol centered on a specific x,y position, you have to calculate the position based on the symbol's width and height; this is problematic since the size of a symbol may change, especially if you're trying to position several different symbols using the same preset variables. To counter this, you can position the original referenced symbol at the 0,0 origin, so when it's referenced, it centers perfectly with the use element's x,y position, shown in this contrasting example, centered-symbol.svg, where a red dot indicates each use element's x,y position:


            

          

Animation Tip: Using 0,0 as the shape's local origin makes it much easier to apply transformations for animations, especially rotation transformations.

TODO: dealing with vector artifacts

Logos

.

TODO: logos and text equivalents

Data Visualizations

The most important aspect of a data visualization is the data itself; the second most important aspect of a data visualization is the framing (or story) that the author is telling about that data; the third most important aspect of a data visualization is the visualization. This is evidenced by the fact that many dynamic data visualizations allow the user to filter and re-sort the data into different graphical representations, from re-ordering bars in a bar chart to changing chart types completely; even in static data visualizations, the same data are often represented in several different ways. Thus, it is important that we emphasize the primacy of the data in the medium of data visualizations (or “dataviz”).

Increasingly, users consume data and information indirectly, and often non-visually. The rise of voice-driven search interfaces in mobile devices, coupled with the search engines behind them, and the text-to-speech presentation of results, highlight that the dissemination of data should not be confined to its visual represenation alone. And yet, conversely, dataviz is also used increasingly, because it helps readers rapidly understand and retain complex information, with less effort. And dataviz is much more easily and compellingly shared on social media than a spreadsheet.

We can have the best of both worlds, the primacy of data and the convenience of dataviz, for almost no cost: we can embed the data itself directly into the dataviz as metadata; indeed, each data point can be embedded directly into that part of the graphic that represents that value. And by doing this in a structured way, the data can be searched, contextualized, extracted, and reused.

TODO: detail embedding data in dataviz, navigation, colors, using right dataviz for data

New Features in SVG 2

There are several new features in SVG 2 that could be included in this authoring guide, based on the rough outline of new features.

Pros

Adding new SVG 2 features to this authoring guide could serve multiple purposes:

Cons

However, there are also reasons not to do this:

Ask if there is significant interest from the developer community in adding explanations and examples of new SVG 2 features to this authoring guide.

Acknowledgments

Members of the SVG Working Group:
Nikos Andronikos (CiSRA/Canon)
Rossen Atanassov (Microsoft)
Tab Atkins Jr. (Google)
Tavmjong Bah (Invited expert)
Dmitry Baranovskiy (Adobe)
Amelia Bellamy-Royds (Invited expert)
Brian Birtles (Mozilla)
Bogdan Brinza (Microsoft)
Rik Cabanier (Adobe)
Cyril Concolato (Institut Telecom)
Erik Dahlström (Invited expert)
Alex Danilo (Google)
Steve Faulkner (The Paciello Group, LLC)
Jun Fujisawa (Canon)
Vincent Hardy (Adobe)
Timothy Horton (Apple)
Koji Ishii (Google)
Dean Jackson (Apple)
Gaurav Jain (Adobe)
Tomoaki Konno (KDDI)
Kelvin Lawrence (IBM)
Chris Lilley (W3C)
Chris Little (Met Office)
Charles McCathie Nevile (Yandex)
Cameron McCormack (Mozilla)
Brian McNeily (SSB BART Group)
Jean-Claude Moissinac (Institut Telecom)
Deblyn Prado (NIC.br)
Leonard Rosenthol (Adobe)
Mark Sadecki (Invited expert)
Doug Schepers (W3C)
Dirk Schulze (Adobe)
Richard Schwerdtfeger (IBM)
Thomas Smailus (Boeing)
Shane Stephens (Google)
Satoru Takagi (KDDI)
Yusuke Uchida (KDDI)
Léonie Watson (The Paciello Group)
Jonathan Watt (Mozilla)
Members of the SVG Accessibility Task Force:
Bellamy-Royds Amelia (Invited expert)
Cooper Michael (W3C Staff)
Esch Fred (IBM)
McCathie Nevile Charles (Yandex)
McCormack Cameron (Mozilla)
McNeily Brian (SSB BART Group)
Migliorisi Heather (Invited expert)
Schepers Doug (W3C Staff)
Schwerdtfeger Richard (IBM)
Watson Léonie (The Paciello Group)
White Jason (Educational Testing Service)