Editorial review: Document the text-box-* properties

[chrisdavidmills]

Description

Chrome 133 and Safari 18.2 support the text-box-* properties from the CSS Inline Layout Module Level 3, which allow you to control how much space is trimmed from the start and/or end block edges of text content.

This PR documents:

• The text-box-trim and text-box-edge properties.
• The text-box shorthand equivalent
• The text-edge datatype
  • Note that this page doesn't include a definition for the leading value. This is because leading is not a <text-edge> value — it's a separate line-fit-edge value. I was initially confused by this because the <text-edge> data type definition is included in the line-fit-edge section (https://drafts.csswg.org/css-inline-3/#text-edges), and the leading value definition is included in the list of <text-edge> values, even though it isn't part of that data type.
• The concept of leading (new glossary entry)

It also updates the CSS inline layout module page to make sure all of these things are linked appropriately.

Motivation

Additional details

ChromeStatus entry: https://chromestatus.com/feature/5174589850648576

Related issues and pull requests

BCD: mdn/browser-compat-data#25730

[github-actions]

Preview URLs (6 pages)

• /en-US/docs/Glossary/Leading
• /en-US/docs/Web/CSS/CSS_inline_layout
• /en-US/docs/Web/CSS/text-box-edge
• /en-US/docs/Web/CSS/text-box-trim
• /en-US/docs/Web/CSS/text-box
• /en-US/docs/Web/CSS/text-edge

External URLs (7)

URL: /en-US/docs/Glossary/Leading
Title: Leading

• https://en.wikipedia.org/wiki/Lead (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Leading (1 time) (Note! This may be a new URL 👀)
• https://matthiasott.com/notes/the-thing-with-leading-in-css (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/CSS/text-edge
Title: <text-edge>

• https://en.wikipedia.org/wiki/CJK_characters (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/CSS/text-box
Title: text-box

• https://developer.chrome.com/blog/css-text-box-trim (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/CSS/text-box-edge
Title: text-box-edge

• https://developer.chrome.com/blog/css-text-box-trim (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/CSS/text-box-trim
Title: text-box-trim

• https://developer.chrome.com/blog/css-text-box-trim (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-02-05 11:31:38)

[hamishwillee]

I'm removing myself from review as "nowhere near as good as @estelle at evaluating CSS PRs". If you want to add me back for bandwidth or other reasons feel free to do so.

[argyleink]

I've gone through all the staged pages, reading them as if I was a fresh developer learning about the topic 🙂 I also did a technical pass looking for accidents or wrong information and I can't find any.

Everything looks good to me!

I'm proud to see similar demo's to those in the Chrome post as well as similar guidance. Glad to know the information we provided has resonated 🙂

[estelle]

partially edited. I don't think "leading" is the right word... so letting you review what we have thus far and decide.

[estelle]

Suggested change

Leading differs across fonts, making consistent typesetting historically challenging on the web. `text-box-edge` — along with its counterpart property {{cssxref("text-box-trim")}}, which specifies which edge(s) to trim leading from — makes consistent typesetting easier to achieve.

Text height differs between fonts, making consistent typesetting historically challenging on the web. The `text-box-edge` — along with its counterpart property {{cssxref("text-box-trim")}} — makes consistent typesetting easier to achieve by enabling trimming of extra spacing above or below text. With the {{cssxref("text-edge")}} properties, we can set the over and under edges for inline boxes. This enables vertically aligning text regardless of the font file's baseline.

[chrisdavidmills]

I'm leaving this one until we can clear up the earlier confusion. Leading must be involved — the relevant spec section is titled Trimming Leading Over/Under Text — but after your review, I'm just confused as to exactly how (although I suspect it is removed from just the start and end of the entire text box).

Again, @argyleink, I'd love to hear your thoughts on this.

[estelle]

Suggested change

	Font files specify an amount of space — termed leading — to be included above and below text, to contain capital letters, ascenders, descenders, etc., and provide spacing between lines. The amount of leading included varies between fonts, making it difficult to consistently set block-level text spacing.
	Font files specify the space included above and below text, to contain capital letters, ascenders, descenders, etc. This in-font spacing ensures lines of text don't overlap by default. The amount of spacing included varies between fonts, making it difficult to consistently set block-level text spacing.

[chrisdavidmills]

Again, I'm leaving this until we clear up the confusion.

[estelle]

Suggested change

	The `text-box-edge` property allows you to trim the leading from the start and/or end edge of the text. It does this by specifying a {{cssxref("<text-edge>")}} value that indicates the over edge and under edge to trim the leading to.
	The `text-box-edge` property allows you to trim the spacing from the start and/or end edge of lines of text by specifying a {{cssxref("<text-edge>")}} value that indicates the over edge and under edge to trim the inline box.

[estelle]

i think we should get rid of this "leading" since that is between lines, not within the inline box. I'll stop editing here and give you a chance to marinate / agree / disagree / get a pint / get several pints ;)

[chrisdavidmills]

I'm leaving this one just for now, until we clear up the confusion.

[estelle]

looking good

[estelle]

Suggested change

	Font files specify an amount of space, termed leading, to be included above and below text to provide spacing between lines. The amount of leading included varies between fonts, as does the space within the font (the height of the capital letter, ascenders, descenders, etc.), making it difficult to consistently set block-level text spacing.
	Font files specify an amount of space, or edge spacing, to be included above and below text to provide spacing between lines. The amount of edge spacing included varies between fonts, as does the space within the font (the height of the capital letter, ascenders, descenders, etc.), making it difficult to consistently set block-level text spacing.

Likely not the right term either, but commenting so we know where/what to update.

[estelle]

Suggested change

We apply a `text-box` value of `trim-both ex alphabetic` to the second one. The {{cssxref("text-box-edge")}} value of `ex alphabetic` specifies to trim the over edge to the font's x-height (the top of the short lower-case letters) and the under edge flush with the text baseline. Because the {{cssxref("text-box-trim")}} value is set to `trim-both`, both the over _and_ under edge are trimmed.

We apply a `text-box` value of `trim-both ex alphabetic` to the second paragraph. The {{cssxref("text-box-edge")}} value of `ex alphabetic` specifies trimming the over edge to the font's x-height (the top edge of short lower-case letters) and the under edge flush with the text baseline. Because the {{cssxref("text-box-trim")}} value is set to `trim-both`, both the over _and_ under edge are trimmed.

[chrisdavidmills]

I applied this one, but made a couple of tweaks.

[estelle]

Suggested change

	The `text-edge` values are used in the {{cssxref("text-box-edge")}} property to define regions of spacing to trim from the block-start edge and block-end edge of specified text content.
	The `<text-edge>` key terms are values of the {{cssxref("text-box-edge")}} property used to specify trim definitions from the block-start edge and block-end edge of text content.

[chrisdavidmills]

I didn't like this suggestion very much. It is technically correct, but I think it will be significantly harder for readers to understand. I have elected to echo the definition from the text-box-edge page, and keep it really simple:

The <text-edge> values are used in the {{cssxref("text-box-edge")}} property to specify an amount of space to trim from text content.

[estelle]

optional: I would put single (and the note) above two keyword values.

[chrisdavidmills]

Yeah, I agree with you — that makes more logical sense for the flow. I've swapped the order over, and I've also swapped the order of the two bullets that precede those sections so that the one > two order is consistent everywhere.