Command structure

Every icon in a rig serialises to the same sequence of path commands. Not the same numbers, the same commands. This is the least obvious constraint in the library and the one with the sharpest failure mode.

What the browser requires

CSS will interpolate the d property between two paths only when their command structure matches. Same number of commands, same types, in the same order.

When it does not match, the value is not animatable, so the browser does the only other thing available: it swaps discretely at the halfway point.

Why everything is a cubic

This is why a straight line is stored as a cubic Bézier with its control points at a third and two thirds of the chord.

Storing lines as L and curves as C would be the obvious representation and would make any icon containing a line unable to morph into one containing a curve. Making everything a C costs four extra numbers per segment and removes the failure entirely.

Why arity is fixed per slot

Same reason, one level up. If slot 0 held one segment in one icon and four in another, the two would serialise to M … C … and M … C … C … C … C … and stop interpolating.

So a rig fixes segments-per-slot, and the importer takes the maximum across the set rather than a compromise. Splitting a cubic is exact, so an icon with fewer segments is subdivided up to the count and nothing is ever approximated.

A test, not a convention

Because the failure is silent, it is asserted rather than documented. Two tests in the library cover it: one checks that every icon in a rig produces identical command structure, and one checks that the browser really does refuse to interpolate mismatched paths.

You can run the same check yourself. validateRig takes a rig and returns a list of everything wrong with it, empty when there is nothing. arrowsRig below is the hand-authored rig from the rig, and the two functions differ only in what they do about a problem: assertRig throws on the first one, which is what you want while authoring, and validateRig reports them all, which is what a build script or an editor wants.

import { validateRig } from "@/lib/morph";

// `assertRig` throws. `validateRig` returns every problem, which is what a build script
// or an editor integration wants.
export const problems = validateRig(arrowsRig);