35 rules

Horizontal spacing and system layout

How much horizontal room does a note need?

Spacing follows a sub-linear curve, not a linear one: a whole note does not get four times a quarter note’s width. On top of that curve, everything a note carries — accidentals, dots, ornaments, grace notes, ledger lines — must claim its own width before the page is laid out, or the column collides with its neighbour.

Breaks the readingCheckable from the score alone
A system break may only fall at a barline, never mid-bar
This is close to inviolable in conventional notation: every system break coincides with the end of a complete measure in every voice simultaneously. A break mid-measure is one of the clearest 'this wasn't professionally engraved' signals.
Breaks the readingNeeds both
A system break must never fall inside a beamed group or a tuplet
A beam is a single visual unit spanning several noteheads with one continuous stroke; a tuplet bracket similarly spans a fixed group of notes with one bracket. Neither can be physically drawn across two separate systems.
Breaks the readingCheckable from the score alone
Automatic whole-staff CSS/viewBox scaling must be the LAST resort after re-breaking is attempted, not the DEFAULT and only fallback
When content does not fit its allotted width, the professional engraving order of operations is: (1) tighten spacing within engraving-minimum limits, (2) re-break into more/shorter systems, (3) as a genuinely last resort, reduce staff size. Reducing staff size as the ONLY fallback is backwards.
Breaks the readingCheckable from the score alone
Every system in a wrapped block must NOT be forced to the identical total width when systems hold different amounts of content
When a system is justified to a fixed width, real engraving keeps NOTE DENSITY (space per beat) roughly consistent across systems and lets total measure count per system vary accordingly — it does NOT take the densest system's ideal width and stretch every OTHER system out to that same absolute width. LilyPond and Dorico both compute spacing per line independently; they never force two lines with different beat totals to the identical rendered width using the per-beat multiplier chosen for a different, denser line.
Breaks the readingNeeds the rendered page
Ground-truth backstop: after render, no note's glyph (head, stem, accidental, or modifier) may extend past the stave's own drawn end-barline position
This is the irreducible, final check beneath every prediction rule in this chapter: whatever the pre-render formula predicts, whatever VexFlow's Formatter decides, the one fact that actually matters to a reader is whether content visibly ran past the barline or off the printed page — a rendered-SVG geometry probe against the ACTUAL drawn stave boundary is the only check that can never be fooled by an error anywhere upstream in the prediction chain.
Breaks the readingCheckable from the score alone
Hand-authored barline positions and the automatic beat-based system-break calculation are two independent sources of truth that can silently disagree
There should be exactly one authority for 'where does bar N end' in a rendering pipeline — deriving barline positions from the time signature and note durations, and deriving system breaks from the SAME derived barline positions, guarantees they can never disagree.
Breaks the readingNeeds the rendered page
Multiple accidentals in one chord column need a stacked-column width, not one accidental's width times the note
When a chord has two or more altered pitches close enough in pitch, their accidentals cannot sit at the same x-offset — they stagger into columns to the left of the notehead, widening that note's footprint well beyond a single-accidental note of the same duration.
Breaks the readingNeeds the rendered page
The pre-render width estimate and VexFlow's real Formatter measurement are two independent computations that can disagree, and the disagreement itself must be checked
Any system that predicts required width BEFORE invoking the real layout engine, in order to make a layout DECISION (choosing `beatW`, choosing to wrap), must be validated against what the real layout engine actually produces — otherwise the decision can be made on a wrong basis and only discovered wrong after the fact, precisely the overflow bug this chapter addresses.
Breaks the readingCheckable from the score alone
THE SPEC: a single pure function computes every note's required width from duration + all attachments + furniture, and a bin-packer decides system breaks against it — BEFORE VexFlow ever runs
This is the capstone rule the others feed into: engraving spacing is not one number (Gradus's current `beatW`) but the sum of a sub-linear duration term, a hard per-note floor, and additive costs for every attachment actually present, evaluated per note, summed per bar, and packed into systems by a solver that treats barline/beam/tuplet boundaries as hard constraints. Every other rule in this chapter that says 'add a term to the shared accumulator' is describing a piece of THIS function.
Misleads the readerCheckable from the score alone
A field that reserves no width because it is never rendered is a silent authoring trap, not a safe no-op
If an authoring surface exposes a property, an author will eventually use it and expect it to appear; a schema field that is accepted but silently dropped fails invisibly, which is worse than a validation error. Fingering numbers do have a real horizontal-spacing convention once implemented (they sit above/below the note and rarely add width, but can when doubled digits or a fingering change appears on a chord).
Misleads the readerCheckable from the score alone
A slur or tie spanning a system break is normal and must be redrawn as two segments, not silently dropped
Unlike beams and tuplets, slurs and ties crossing a system break are completely standard — the curve is drawn open-ended at the right edge of the first system and resumes open-ended at the left edge of the next. This is NOT a fault to prevent by re-breaking; it is a rendering case that must be HANDLED.
Misleads the readerNeeds both
Accidentals must add horizontal width to their note's column, and the pre-render estimate must account for it
An accidental sits to the left of its notehead and needs its own reserved horizontal room — Gould and Ross both treat accidental clearance as a first-class width contributor, not an afterthought absorbed into general note spacing; SMuFL glyph-advance metadata gives each accidental its own width the layout engine must add.
Misleads the readerCheckable from the score alone
An accidental already implied by the key signature must not be re-drawn (and must not reserve extra width)
Once a key signature raises or lowers a pitch class, individual notes of that pitch class do NOT carry a redundant accidental unless a courtesy accidental is deliberately used (e.g. after a chromatic alteration earlier in the bar, or by house-style choice). VexFlow itself ships a `KeyManager` specifically to suppress this redundancy, and Gradus does not use it.
Misleads the readerCheckable from the score alone
An underfull final system should not be force-justified to the same width as full systems
When a piece ends partway through what would otherwise be a full system's worth of bars, standard practice leaves that final system at its NATURAL (density-consistent) width rather than stretching it to match the page/column width.
Misleads the readerCheckable from the score alone
Any caller-supplied option override to the public Notation API's Verovio renderer must disable automatic breaking ONLY when paired with an explicit, content-derived break-insertion mechanism — never bare
Verovio's `breaks: 'auto'` with a fixed `pageWidth` is professionally-correct default behavior — automatic re-breaking to a known page width. Overriding to manual/encoded breaking is legitimate ONLY when the caller has independently computed and inserted the actual break points into the document (e.g. explicit `<print new-system="yes">` markers) — an override that disables auto-breaking WITHOUT supplying real break points reproduces the 'one giant unbroken system' hazard this whole chapter exists to prevent.
Misleads the readerNeeds both
Dynamic markings (Annotation) below the staff must not horizontally collide with the dynamic on an adjacent note
A dynamic letter placed below a note occupies real horizontal room at that vertical band; if two dynamics fall on closely-spaced notes, their text can overlap even though the noteheads themselves don't collide.
Misleads the readerCheckable from the score alone
Every notehead needs a minimum absolute width regardless of duration
No note, however short, may be crushed below the space its notehead, stem, and immediate neighbor-clearance require — there is a hard floor beneath which noteheads visually collide. Ross and Gould both treat this as the innermost constraint the proportional curve sits on top of; SMuFL's `engravingDefaults` metadata encodes a font's minimum glyph advance widths at a given staff size, which is the authoritative source for this floor.
Misleads the readerCheckable from the score alone
Key-signature furniture width must scale with the actual number of accidentals in the signature, not a 3-tier bucket
A key signature's rendered width is directly proportional to how many sharp or flat glyphs it contains (1 through 7) — this is purely mechanical (each accidental glyph has a fixed advance width) and any width model that doesn't scale per-accidental will systematically misjudge signatures at the extremes.
Misleads the readerCheckable from the score alone
Note spacing must follow a sub-linear (logarithmic) duration curve, not linear beats × width
The horizontal space allotted to a note must grow more slowly than its duration: doubling a note's duration should roughly multiply its space by ~1.5-1.7x, not 2x. This is the Wanske/Gourlay proportional-spacing model LilyPond implements explicitly (space = base + k·log2(duration/shortest-duration-on-the-line)) and that Ross's engraving spacing tables approximate empirically (his tables compress the ratio between a half note and an eighth note to well under 4:1 even though the beat ratio is 4:1).
Misleads the readerNeeds both
Notes on ledger lines need extra horizontal side-clearance beyond in-staff notes of the same duration
A ledger line extends beyond the notehead on both sides (SMuFL's `engravingDefaults.legerLineExtension` is exactly this metric), and adjacent ledger-line notes need enough horizontal gap that their ledger lines don't visually merge or overlap another note's ledger lines.
Misleads the readerCheckable from the score alone
The pre-render width estimate and the Formatter's own fallback margin must agree on whether the FIRST system reserves extra width for the time signature
A time signature is only drawn once, on the first system — its width must be reserved on that system specifically, not spread flatly across every system.
Misleads the readerCheckable from the score alone
The print/keepsake pipeline's per-bar page-width allocation is a FIXED constant regardless of note density, reproducing the JSX renderer's core defect on the second surface
A system's required width is a function of what its bars actually contain (proportional duration curve + attachments), not a flat width-per-bar constant — the same principle spacing-uniform-system-width-vs-variable-density and bars-per-system-density-driven-not-fixed establish for the JSX surface applies identically here, since the underlying music-notation physics don't change between renderers.
Falls short of best practiceCheckable from the score alone
A system's left margin must widen when the FIRST note of that system carries an accidental
Optical/left-edge alignment: the visual 'start' of a system is the leftmost notehead, but if that first note has an accidental, the accidental — not the notehead — becomes the true left edge, and the system's furniture must leave room for it. Ross calls this the distinction between optical and mathematical spacing.
Falls short of best practiceCheckable from the score alone
Articulations (staccato, accent, tenuto, marcato, fermata) mostly need NO horizontal spacing term — but must not be summed like accidentals when stacked
Unlike accidentals or dynamics, articulation glyphs are centered directly on the notehead's own x-position rather than needing dedicated clearance before or after it; most articulation glyphs are narrower than or comparable to a notehead. The one outlier is fermata, whose glyph is visibly wider than a notehead. Gould and Ross both place articulations as vertical, not horizontal, spacing concerns except at extreme note density.
Falls short of best practiceCheckable from the score alone
Augmentation dots must add horizontal width in the PRE-RENDER estimate, not just at VexFlow draw time
A dot sits to the right of a notehead and consumes its own small but nonzero width; dotted rhythms are common enough in Gradus's chorale and hymn-tune content that omitting dot width from the pre-render estimate systematically under-predicts required width for exactly the material most likely to need wrapping.
Falls short of best practiceCheckable from the score alone
Clef, key-signature, time-signature, and opening-barline width must be tracked as four separate, independently-correct terms, not one lump constant
Each element of a system's opening furniture has its own, independently well-defined width (a clef glyph's advance width, a key signature's accidental count, a time signature's digit-column width, an opening barline's stroke width) — collapsing them into one constant makes it impossible to fix one term (e.g. correct the key-signature bucket, per spacing-furniture-keysig-graduated-width) without also silently affecting the others, and makes it impossible to diagnose WHICH element under- or over-reserved space when a block overflows.
Falls short of best practiceCheckable from the score alone
Every system must repeat its clef and key signature; the time signature and an opening repeat sign appear only on the first system, the closing repeat only on the last — this is currently CORRECT and must not regress
A clef and key signature are drawn at the start of every system (a reader who jumps to any line mid-piece must be able to read it without scrolling back); the time signature, by contrast, is drawn only once, at the true beginning of the piece, and is understood to persist. Courtesy clef/key-signature marks at the END of a system (warning of an upcoming CHANGE) are a distinct, separate convention that only applies when the clef/key actually changes mid-piece.
Falls short of best practiceCheckable from the score alone
First-system indent (for a title) is a real convention but should NOT be enforced in Gradus's current design
Traditionally, the first system of a piece is indented from the left margin to leave visual room for the title/composer credit printed above the staff.
Falls short of best practiceCheckable from the score alone
Grace notes must reserve their own horizontal width ahead of the main note
A grace note (or grace-note group) draws at reduced size immediately before its principal note and needs real horizontal room of its own — it does not compress the principal note's space, it ADDS width before it.
Falls short of best practiceCheckable from the score alone
Gradus's notation model has no way to author a mid-piece clef or key-signature change, which also means it has no courtesy-clef/key-at-system-end mechanism
When a piece changes clef or key partway through, courtesy convention prints the NEW clef/key at the END of the preceding system in addition to the full clef/key at the start of the following system — a system-layout-adjacent width cost that only exists because clef/key changes exist at all.
Falls short of best practiceCheckable from the score alone
Ornament glyphs (trill, turn, mordent) need horizontal room above the note distinct from the notehead's own footprint
An ornament glyph sits above the staff and can be visually wider than the notehead it decorates — if the note's own spacing doesn't leave room, the ornament collides with the ornament (or accidental, or slur) on the adjacent note. A sustained trill additionally draws a wavy extension line for its full duration, a horizontal-space commitment the note's own duration-based space may not otherwise provide.
Falls short of best practiceCheckable from the score alone
Page-turn placement is out of scope for the web lesson surface but directly applies to Gradus's print/export (scoreGifts) pipeline
Page turns should never fall in the middle of a phrase if avoidable, and a performer needs enough rest (a bar or more, or a held note) immediately before a turn to physically turn the page — this only matters for paginated, printed output, not a single continuously-scrolling web SVG.
Falls short of best practiceCheckable from the score alone
The end-of-system barline and right margin must account for repeat-end / final barline glyph width, not a flat constant
A repeat-end barline (thin+thick line with dots) and a final barline are visually and dimensionally wider than an ordinary single barline; the right margin at a system's end must be large enough for whichever barline glyph will actually be drawn there.
Falls short of best practiceCheckable from the score alone
The number of bars per system must be chosen by that system's own note density, not a single fixed count applied to the whole block
Gould is explicit that the number of measures per line is governed by how much content those measures contain, not a target count decided in advance — a system of eighth-note-dense bars legitimately holds fewer bars than a system of half-note-sparse bars, on the SAME page.
Falls short of best practiceCheckable from the score alone
When a note carries a lyric syllable, the syllable's text width — not the note's duration — must govern that note's minimum horizontal space
A long syllable under a short note forces that note (and often its neighbors) to widen beyond what its duration alone would earn, because the text must not overlap the next syllable. Ross and Gould both treat lyric-driven spacing as an override layer on top of, not instead of, the duration curve.

Loading…

A system break may only fall at a barline, never mid-bar

A system break must never fall inside a beamed group or a tuplet

Automatic whole-staff CSS/viewBox scaling must be the LAST resort after re-breaking is attempted, not the DEFAULT and only fallback

Every system in a wrapped block must NOT be forced to the identical total width when systems hold different amounts of content

Ground-truth backstop: after render, no note's glyph (head, stem, accidental, or modifier) may extend past the stave's own drawn end-barline position

Hand-authored barline positions and the automatic beat-based system-break calculation are two independent sources of truth that can silently disagree

Multiple accidentals in one chord column need a stacked-column width, not one accidental's width times the note

The pre-render width estimate and VexFlow's real Formatter measurement are two independent computations that can disagree, and the disagreement itself must be checked

THE SPEC: a single pure function computes every note's required width from duration + all attachments + furniture, and a bin-packer decides system breaks against it — BEFORE VexFlow ever runs

A field that reserves no width because it is never rendered is a silent authoring trap, not a safe no-op

A slur or tie spanning a system break is normal and must be redrawn as two segments, not silently dropped

Accidentals must add horizontal width to their note's column, and the pre-render estimate must account for it

An accidental already implied by the key signature must not be re-drawn (and must not reserve extra width)

An underfull final system should not be force-justified to the same width as full systems

Any caller-supplied option override to the public Notation API's Verovio renderer must disable automatic breaking ONLY when paired with an explicit, content-derived break-insertion mechanism — never bare

Dynamic markings (Annotation) below the staff must not horizontally collide with the dynamic on an adjacent note

Every notehead needs a minimum absolute width regardless of duration

Key-signature furniture width must scale with the actual number of accidentals in the signature, not a 3-tier bucket

Note spacing must follow a sub-linear (logarithmic) duration curve, not linear beats × width

Notes on ledger lines need extra horizontal side-clearance beyond in-staff notes of the same duration

The pre-render width estimate and the Formatter's own fallback margin must agree on whether the FIRST system reserves extra width for the time signature

The print/keepsake pipeline's per-bar page-width allocation is a FIXED constant regardless of note density, reproducing the JSX renderer's core defect on the second surface

A system's left margin must widen when the FIRST note of that system carries an accidental

Articulations (staccato, accent, tenuto, marcato, fermata) mostly need NO horizontal spacing term — but must not be summed like accidentals when stacked

Augmentation dots must add horizontal width in the PRE-RENDER estimate, not just at VexFlow draw time

Clef, key-signature, time-signature, and opening-barline width must be tracked as four separate, independently-correct terms, not one lump constant

Every system must repeat its clef and key signature; the time signature and an opening repeat sign appear only on the first system, the closing repeat only on the last — this is currently CORRECT and must not regress

First-system indent (for a title) is a real convention but should NOT be enforced in Gradus's current design

Grace notes must reserve their own horizontal width ahead of the main note

Gradus's notation model has no way to author a mid-piece clef or key-signature change, which also means it has no courtesy-clef/key-at-system-end mechanism

Ornament glyphs (trill, turn, mordent) need horizontal room above the note distinct from the notehead's own footprint

Page-turn placement is out of scope for the web lesson surface but directly applies to Gradus's print/export (scoreGifts) pipeline

The end-of-system barline and right margin must account for repeat-end / final barline glyph width, not a flat constant

The number of bars per system must be chosen by that system's own note density, not a single fixed count applied to the whole block

When a note carries a lyric syllable, the syllable's text width — not the note's duration — must govern that note's minimum horizontal space