42 rules

Vertical spacing and collisions

What must not touch what?

The rules that decide whether marks collide once the page is engraved. Seconds inside a chord offset across the stem, unisons share a notehead, accidentals stagger, stems stay out of beams they do not belong to, and a voice’s noteheads stay clear of a neighbouring voice’s stem corridor.

Breaks the readingCheckable from the score alone
A mark's structural side is fixed by stem direction or part convention at authoring time and must never be silently flipped to resolve a collision
When resolving a local vertical collision, FLIPPING a mark's canonical side is worse than nudging the colliding glyph horizontally or increasing staff-to-staff distance, because a flipped mark reads as a different instruction.
Breaks the readingNeeds the rendered page
A slur must clear every intermediate notehead under its span, not just its two endpoints
A slur arcs from its first note to its last note and must stay clear of every notehead (and stem/beam) IN BETWEEN, bulging further out when an intermediate note is higher (for a slur above) or lower (for a slur below) than the endpoints.
Breaks the readingNeeds the rendered page
A slur passing over or under a beamed group must clear the beam's ink, not just the notes' stems
When a slur's span includes beamed notes, the beam itself (which projects beyond the stem tips and slants with the group) is part of what the slur must clear.
Breaks the readingNeeds the rendered page
All dynamics in one system share a single baseline; they are not each individually centered under their own note's height
Dynamics across a system are drawn at one consistent y (the baseline for that staff's dynamics row), regardless of whether the notes above them are high or low in the staff.
Breaks the readingNeeds the rendered page
An accidental must clear a minimum gap from its own notehead and from the previous note's glyphs
An accidental sits immediately to the left of its notehead with a small fixed clearance — close enough to read as attached, never touching the notehead or overlapping a preceding note's stem/flag/dot.
Breaks the readingNeeds both
Fermata and marcato always sit outside every other mark on the note, overriding normal side/stack rules
Fermata and marcato must remain unambiguous regardless of what else is attached to the note, so they are placed outside the staff and outside any other stacked mark on that note — the one exception to the otherwise-consistent notehead-side rule (vs-articulation-notehead-side-default): fermata/marcato ignore stem direction and sit above the note (or below, only if the whole passage sits below the staff already).
Breaks the readingNeeds both
Multiple accidentals within one chord must stagger further left when they would overlap each other
When a chord carries two or more accidentals close in pitch, the accidentals cannot sit in one vertical column — the lower one is pushed further left so the two glyph bounding boxes clear.
Breaks the readingNeeds both
Seconds inside a chord must offset noteheads left/right of the stem
When two pitches in the same chord are a 2nd apart, the higher notehead is drawn on the normal (stem-appropriate) side and the lower is displaced to the opposite side of the stem so the two notehead bounding boxes do not overlap.
Breaks the readingNeeds both
Single articulation marks default to the notehead side, opposite the stem
Staccato dot, accent, and tenuto are placed on the notehead side of the note — opposite the stem direction: stem up → mark below the notehead; stem down → mark above.
Breaks the readingNeeds the rendered page
Staff-to-staff distance must grow per system to accommodate whatever is drawn between the staves in THAT system — not a fixed constant across the whole piece
The gap between two staves is not uniform across a piece; it must expand in any system where content between them needs more room than the piece's baseline gap provides — computed per system via a skyline (top/bottom envelope) comparison, not a single global constant.
Breaks the readingNeeds both
Text elements attached at a fixed offset from one staff must not land on an adjacent staff in any multi-stave layout — the general form of the confirmed note-label/dynamic bug
Any text whose vertical position is computed as 'staff Y plus a constant' rather than 'staff Y, clamped to stay clear of the next staff's content' will collide whenever the next staff is closer than that constant.
Breaks the readingCheckable from the score alone
Two identical pitches in one chord must share a single notehead, not render as two coincident noteheads
When two voice parts land on the exact same pitch at the exact same onset within what Gradus encodes as a single chord array (e.g. `pitch: ['C4','C4']`), standard engraving draws ONE notehead, not two stacked copies — a duplicated pitch in a chord array is an authoring error, not a legitimate unison-in-chord notation (real cross-voice unison is a DIFFERENT case, see vs-cross-voice-unison-collision, which uses two independent voices, not one chord array).
Breaks the readingNeeds both
Two voices sharing a stave and a register must not lattice their beams through each other's noteheads
When two voices run continuous short-value beamed passages through the same tessitura on one stave, the upper voice's beam (above its stems) and the lower voice's beam (below its stems) can weave through the middle of the staff and strike the OTHER voice's noteheads even with zero real voice-crossing. The fix is structural (separate staves / open score), not a nudge.
Breaks the readingNeeds both
Two voices sharing one stave must not silently stack a unison/near-unison note
When two independent voices share a stave (SATB soprano+alto on the treble stave, tenor+bass on the bass stave), their noteheads must be joined into one ModifierContext so overlapping or near-overlapping pitches between the voices get offset exactly like a chord's seconds rule; treating each voice's Formatter independently silently draws both noteheads on top of each other.
Misleads the readerNeeds the rendered page
A dynamic mark below the staff must clear the stem/notehead it is attached to
A dynamic letter sits below the staff at a fixed minimum distance from the bottom line, but must also clear any stem that projects down toward it from a low note.
Misleads the readerNeeds the rendered page
A fingering numeral must clear the notehead, stem, and any other mark on that note, and yields its position to nothing (it is innermost per the canonical stack order)
A fingering number sits immediately adjacent to its notehead, on the side opposite the stem, and is the innermost item in the stack.
Misleads the readerNeeds the rendered page
A hairpin must vertically align with, and horizontally abut, the dynamic marks that bracket it
A crescendo/decrescendo wedge is drawn at the same baseline height as the dynamic letters it connects, and its narrow point should nearly touch the adjacent dynamic's glyph edge.
Misleads the readerNeeds the rendered page
A stem must not pass through a beam it is not part of
When a voice's stem tip reaches toward the opposite voice's staff-half, it must not cross through that other voice's beam ink — a stem is a single thin line but a beam is a filled polygon with real height, so a stem tip that only just clears a note by the vs-notehead-stem-adjacent-voice margin can still pass straight through the wider beam band a few pixels further along the same x.
Misleads the readerNeeds the rendered page
A tie between two ledger-line notes must clear the ledger line stubs of both
When a tie connects two notes that both sit on/above/below ledger lines, its arc must clear the ledger-line stubs at both ends.
Misleads the readerNeeds the rendered page
A voice's notehead must not fall inside a neighboring voice's stem corridor
A stem occupies a thin vertical corridor (stemThickness, SMuFL default ~0.12sp) from notehead to beam/flag; another voice's notehead landing inside that corridor at the same x reads as a smear even if the noteheads themselves don't touch.
Misleads the readerNeeds the rendered page
An accidental attached to a ledger-line note must clear the ledger line stub
A note on or near a ledger line has a short horizontal stub extending past the notehead on both sides (SMuFL legerLineExtension, default ~0.4sp per side); an accidental to that note's left must sit clear of that stub.
Misleads the readerNeeds the rendered page
An articulation mark must sit within a fixed distance band from its notehead — neither touching it nor floating disconnected
Distinct from WHICH side the mark sits on (vs-articulation-notehead-side-default): the mark must be close enough to read as attached to its own note, and far enough not to visually merge with the notehead ink.
Misleads the readerNeeds the rendered page
An articulation mark on a note under a slur must not poke through the slur's curve
When a note carries both an articulation (typically staccato, in a portato passage) and sits under a slur, the articulation mark stays BETWEEN the notehead and the slur's arc — it must not project past the slur line to the outside, which would read as floating disconnected from the phrase the slur marks.
Misleads the readerNeeds the rendered page
An articulation mark whose notehead sits ON a staff line must clear that line, not sit on top of it
When a note's notehead is exactly on a staff line (not a space), the articulation mark placed close to the notehead must not visually merge with the staff line itself.
Misleads the readerNeeds the rendered page
An ornament glyph above a beamed group must clear the beam, not the flag it doesn't have
Trill/turn/mordent glyphs sit above the staff (or above the note) and, on a beamed note, must clear the beam's ink the same way they'd clear a flag on an unbeamed note.
Misleads the readerNeeds the rendered page
Articulation on a ledger-line note moves further out but stays on the notehead side
When the notehead sits on or beyond a ledger line, the articulation mark is pushed an extra increment further from the staff rather than crowding the ledger line — but it stays on the SAME (notehead) side determined by stem direction; it does not flip sides.
Misleads the readerCheckable from the score alone
Default rest positions for two voices on one stave must be pre-separated
Two voices sharing a stave both default a rest to the stave's middle line; if left alone they stack. Standard practice (and Gradus's own fix) pushes the upper voice's rest up and the lower voice's rest down along the same axis the forced stem direction already separates them on.
Misleads the readerNeeds the rendered page
Multiple lyric verses maintain consistent line-to-line spacing without a melisma extension colliding with the next verse line
When a piece carries multiple lyric verses stacked below one staff, each verse line sits at a consistent vertical increment from the one above; a melisma line/extension must not visually collide with the next verse's text.
Misleads the readerNeeds both
Slur curvature must scale with the span it covers and the height of its highest/lowest intervening note
A slur's control points must be computed from (a) the horizontal distance between its endpoints, and (b) the highest (or lowest) intervening notehead it must clear.
Misleads the readerNeeds both
Two slurs that overlap in note-range must nest with visibly different curve depths, not coincide
When one slur (a phrase mark) and another (a shorter articulation slur) cover overlapping note ranges, the outer slur must be drawn with visibly greater depth than the inner one.
Misleads the readerNeeds both
Two voices sharing a stave must not stack their accidentals at the same onset without staggering
When two independent voices (not one chord) sound a note requiring an accidental at the same onset on a shared stave, both accidentals sit to the left of their respective noteheads at roughly the same x — exactly the same column-collision risk vs-accidental-chord-stagger solves for one chord, but ACROSS voices, where VexFlow's own per-voice ModifierContext does not automatically coordinate them the way `fmt.joinVoices()` coordinates noteheads (per vs-cross-voice-unison-collision).
Misleads the readerNeeds the rendered page
When both a dynamic mark and a lyric occupy the space below a staff, they must stack (dynamic further out) rather than overlap
Lyrics sit immediately below the staff; dynamics, when present on the same system, are pushed further below the lyric line.
Misleads the readerNeeds both
When multiple marks combine on one note, they stack in a fixed order outward from the notehead: fingering, then articulation, then ornament, then slur/tie, with dynamics/tempo text further out still
Fingering sits closest to the notehead; next out is articulation; ornaments sit outside articulation; ties/slurs are drawn outside all of the above since the curve must arc over everything attached to the note; dynamics and tempo/expression text sit outermost.
Falls short of best practiceNeeds the rendered page
A dynamic mark is horizontally centered on its own note's x position, not left/right-justified against it
A dynamic letter's horizontal center aligns with the notehead it belongs to, so the mark reads unambiguously as attached to that specific note rather than the one before or after it.
Falls short of best practiceNeeds the rendered page
A lyric syllable must clear a ledger line belonging to a note directly above it
When a low note requiring ledger lines sits directly above where a lyric syllable is placed, the syllable text must not overlap the ledger line stub extending down from that note.
Falls short of best practiceNeeds the rendered page
A staff reserves a baseline minimum space above and below itself even with no extra content
Even a bare staff reserves roughly one staff-space above its top line and below its bottom line before any adjacent element may begin — engraving's floor, not its ceiling; every rule above ADDS to this floor when content requires more.
Falls short of best practiceNeeds the rendered page
A tie arc crossing a staff line must bulge enough to read as a single clean crossing, not clip the line at a shallow angle
A tie between two notes on a space, when its arc must cross a staff line to connect them, should cross that line cleanly rather than running nearly parallel to it for a long stretch.
Falls short of best practiceNeeds both
A tuplet bracket/number must clear the beam it runs parallel to, or be omitted when the beam alone is unambiguous
A tuplet bracket is drawn only when the group is NOT already beamed together; when a bracket IS drawn (unbeamed tuplet), it must clear the noteheads/stems it spans.
Falls short of best practiceNeeds both
An isolated local collision is resolved by nudging the one colliding glyph; three or more consecutive colliding slots means the underlying spacing is too tight and must be widened globally instead
Displacing a single glyph a small horizontal amount is the correct fix for an ISOLATED collision. But when a RUN of consecutive note-slots all require displacement, individually nudging each one produces a visually uneven, 'stair-stepped' result — the correct fix is to increase the passage's overall horizontal spacing rather than keep displacing.
Falls short of best practiceNeeds the rendered page
Articulations on notes under one beam should read at a visually consistent height across the group, not fluctuate per notehead
When several beamed notes each carry the same articulation (e.g. a run of staccato eighth notes), the marks are conventionally kept at a roughly even distance from the beam/staff across the group — engravers avoid a staircase of wildly different offsets even though each note's raw stem-height differs, because the beam itself (not each individual notehead) is what the eye reads the marks against.
Falls short of best practiceCheckable from the score alone
Canonical priority order of items stacked on one side of a note, from the notehead outward
From the notehead outward: (1) notehead + its own accidental/ledger lines, (2) fingering, (3) articulation, (4) ornament, (5) slur/tie arc, (6) dynamics/hairpin, (7) tempo/expression/rehearsal text, (8) fermata and marcato (ALWAYS outermost, overriding the above order entirely per vs-fermata-marcato-always-outside).
Falls short of best practiceCheckable from the score alone
Two simultaneous articulations on one note (e.g. accent + staccato, a portato/marcato-staccato combination) must combine or stack per convention — currently unrepresentable in Gradus, which is itself the correct state
Combined articulations (accent+staccato, tenuto+staccato as portato) are engraved either as a single combined glyph or as two small marks stacked tightly on the same side, never as two full-size marks independently spaced per vs-articulation-notehead-clearance-gap's normal band.

Loading…

A mark's structural side is fixed by stem direction or part convention at authoring time and must never be silently flipped to resolve a collision

A slur must clear every intermediate notehead under its span, not just its two endpoints

A slur passing over or under a beamed group must clear the beam's ink, not just the notes' stems

All dynamics in one system share a single baseline; they are not each individually centered under their own note's height

An accidental must clear a minimum gap from its own notehead and from the previous note's glyphs

Fermata and marcato always sit outside every other mark on the note, overriding normal side/stack rules

Multiple accidentals within one chord must stagger further left when they would overlap each other

Seconds inside a chord must offset noteheads left/right of the stem

Single articulation marks default to the notehead side, opposite the stem

Staff-to-staff distance must grow per system to accommodate whatever is drawn between the staves in THAT system — not a fixed constant across the whole piece

Text elements attached at a fixed offset from one staff must not land on an adjacent staff in any multi-stave layout — the general form of the confirmed note-label/dynamic bug

Two identical pitches in one chord must share a single notehead, not render as two coincident noteheads

Two voices sharing a stave and a register must not lattice their beams through each other's noteheads

Two voices sharing one stave must not silently stack a unison/near-unison note

A dynamic mark below the staff must clear the stem/notehead it is attached to

A fingering numeral must clear the notehead, stem, and any other mark on that note, and yields its position to nothing (it is innermost per the canonical stack order)

A hairpin must vertically align with, and horizontally abut, the dynamic marks that bracket it

A stem must not pass through a beam it is not part of

A tie between two ledger-line notes must clear the ledger line stubs of both

A voice's notehead must not fall inside a neighboring voice's stem corridor

An accidental attached to a ledger-line note must clear the ledger line stub

An articulation mark must sit within a fixed distance band from its notehead — neither touching it nor floating disconnected

An articulation mark on a note under a slur must not poke through the slur's curve

An articulation mark whose notehead sits ON a staff line must clear that line, not sit on top of it

An ornament glyph above a beamed group must clear the beam, not the flag it doesn't have

Articulation on a ledger-line note moves further out but stays on the notehead side

Default rest positions for two voices on one stave must be pre-separated

Multiple lyric verses maintain consistent line-to-line spacing without a melisma extension colliding with the next verse line

Slur curvature must scale with the span it covers and the height of its highest/lowest intervening note

Two slurs that overlap in note-range must nest with visibly different curve depths, not coincide

Two voices sharing a stave must not stack their accidentals at the same onset without staggering

When both a dynamic mark and a lyric occupy the space below a staff, they must stack (dynamic further out) rather than overlap

When multiple marks combine on one note, they stack in a fixed order outward from the notehead: fingering, then articulation, then ornament, then slur/tie, with dynamics/tempo text further out still

A dynamic mark is horizontally centered on its own note's x position, not left/right-justified against it

A lyric syllable must clear a ledger line belonging to a note directly above it

A staff reserves a baseline minimum space above and below itself even with no extra content

A tie arc crossing a staff line must bulge enough to read as a single clean crossing, not clip the line at a shallow angle

A tuplet bracket/number must clear the beam it runs parallel to, or be omitted when the beam alone is unambiguous

An isolated local collision is resolved by nudging the one colliding glyph; three or more consecutive colliding slots means the underlying spacing is too tight and must be widened globally instead

Articulations on notes under one beam should read at a visually consistent height across the group, not fluctuate per notehead

Canonical priority order of items stacked on one side of a note, from the notehead outward

Two simultaneous articulations on one note (e.g. accent + staccato, a portato/marcato-staccato combination) must combine or stack per convention — currently unrepresentable in Gradus, which is itself the correct state