Hephaestus is pre-1.0: only the latest release is supported, and a minor release can require action. Read the compatibility policy.
Skip to Content
Hephaestus

Practice visual rules

The SVG markup and Markdown that Hephaestus accepts in a practice visual and guide, the theme color classes, and the starter templates.

This page lists what Hephaestus accepts in the visual and the guide of a practice. Hephaestus checks each visual, guide, and figure when you save the practice. If it refuses the save, its message names the element, the attribute, or the limit. Practices gives the steps to add a visual and a guide.

What Hephaestus accepts

RuleLimit
Root element<svg xmlns="http://www.w3.org/2000/svg" viewBox="…">
File size64 KB or less for each SVG
Elementssvg, g, path, rect, circle, ellipse, line, polyline, polygon, text, tspan, title, desc
AttributesGeometry and presentation only. The list follows this table.
Attribute valuesLetters, digits, spaces, and the characters # . , % + ( ) / - _. Thus, a value cannot contain a url(...) reference, a quote, or an escape.
Not acceptedIds, the style attribute and element, links, a DOCTYPE, scripts, images, CDATA sections, processing instructions, and comments that contain < or >
Visual description1 to 300 characters
Guide textMarkdown with no HTML, 12,000 characters or fewer
Links in a guideWeb addresses that start with https:// or http://
Figures4 or fewer for each guide. A figure name has lowercase letters, digits, and single hyphens.
Images in a guideOnly the guide's own figures, each with a description and the source figures/<name>.svg. Add figure writes this line for you.

The accepted attributes are: viewBox, width, height, preserveAspectRatio, version, x, y, x1, y1, x2, y2, cx, cy, r, rx, ry, d, points, dx, dy, transform, class, fill, fill-rule, fill-opacity, clip-rule, stroke, stroke-width, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-dasharray, stroke-dashoffset, stroke-opacity, opacity, font-size, font-weight, font-style, text-anchor, dominant-baseline, letter-spacing, vector-effect, role, aria-hidden, focusable, and xml:space.

Most drawing tools add ids, styles, or gradients. Remove them before you upload the file. Without ids, a picture cannot use markers, gradients, masks, filters, or clip paths. Draw an arrowhead as a small filled triangle.

Colors in light and dark mode

A pv-* class gives a shape a color of the app theme. The color changes with the theme, so one file works in both themes.

ClassColor
pv-fill-inkFill with the main text color
pv-fill-mutedFill with the secondary text color
pv-fill-surfaceFill with the panel background
pv-fill-accentFill with the accent color
pv-fill-accent-softFill with the accent color at 15% opacity
pv-stroke-inkStroke with the main text color
pv-stroke-mutedStroke with the secondary text color
pv-stroke-lineStroke with the border color
pv-stroke-accentStroke with the accent color
pv-monoThe code font of the app, for one code token in a label of size 15

Set fill="none" on a shape that has only a stroke. A visual with no pv-* class keeps its own colors. The panel shows it on a light surface in both themes.

Starter templates

Each template uses only accepted markup and pv-* classes, with placeholder labels:

  • Contrast pair: the work without the practice on the left, and the same work with it on the right. Use it unless a fork or a sequence fits better.
  • Fork: one event, then the lapse on top and the practice below.
  • Sequence: three steps in order, for a figure in a guide. A visual uses it only to compare two orders, as two rows.

A copy of a template can be edited in a text editor or a drawing tool. The height of its viewBox must reach the bottom of the lowest shape.