docs(templates): lineSpacing is points, not a multiple of the font size - #503
Merged
Conversation
The authoring cheatsheet's address-block recipe passed 1.3 and explained it as overriding a default of 1.0 — the reading a CSS line-height invites, and the one the number itself suggests. lineSpacing is extra space in points, defaulting to 0: a paragraph grows by (lines - 1) * spacing, so 1.3 bought a little over one point of air rather than 30% more leading, and there was no 1.0 default to override. The recipe and the full template listing below it now pass a value that does what the prose beside them promises, and the page states the unit.
DemchaAV
force-pushed
the
docs/line-spacing-units
branch
from
August 4, 2026 11:47
92ef286 to
312bd76
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The v1-classic authoring cheatsheet taught
lineSpacingas a leading multiplier. Itsaddress-block recipe passed
1.3with the comment "default 1.0 squashes \n-joinedlines" — both halves wrong, and wrong in the direction a reader coming from CSS
line-heightalready leans.lineSpacingis extra space in points.ParagraphBuilderinitialises it to0.0and
TextFlowSupportapplies it astotalHeight += (lineCount - 1) * gap, so1.3bought a little over one point of air rather than 30% more leading, and no
1.0default ever existed to override.
The page is archived — it carries its own banner saying so, and
which-template-system.mdlists it under Historical (archived). It is still worthcorrecting, because the error is not about the removed surface the banner disclaims:
ParagraphBuilder.lineSpacing(double)exists unchanged in 2.x with the samepoints-based semantics. The page's stated audience is someone maintaining a pre-2.0
caller, and this sentence would send them into 2.x code with the wrong model of a
method that never changed. "Not updated anymore" is a promise to stop adding new
material, not a licence to leave a false statement standing.
What
3and says what the unit is: extra points, default0, heightgrows by
(lines - 1) × spacing.1.3in the full template listing further down the page is corrected too —leaving it would have kept the misreading one scroll away.
lineSpacing(1.3)as the address-blockrecipe.
Checked the rest of the public docs for the same claim:
docs/recipes/lists.md,rich-text.mdandshapes.mdalready describe it as a gap and pass point-shapedvalues, so this page was the only one teaching the multiplier reading.
Tests
./mvnw -B -ntp clean verify→BUILD SUCCESS. No marked snippets on this page, sothe change is prose and sample values only; the guards that read it
(
DocsBoldFaceGuardTest,CanonicalSurfaceGuardTest, link checks) pass.