When text runs out of room
intermediate·7 min·Markdown for agents
What this lesson teaches
Decide per field whether text wraps, truncates at the end or the middle, or stays whole; stop long words breaking boxes; and hold the size and contrast floors.
Three files, all named almost the same. Narrow the column with end-truncation on, and try to tell which is which.
Tap a row for its full name: truncation is only allowed with a way back to the whole string. The size never truncates; values people compare stay whole.
With end-truncation they all become Q3-board-report-fi…. Identical. Switch to middle-truncation and the part that differs, the end, survives.
Truncation deletes information
means cutting text with an ellipsis (…). The skill treats it as deleting information, so it is only allowed with a route back to the whole string: a tooltip that also opens on keyboard focus, an expand control, or a detail view. A clipped ID with no way to read it is data loss wearing CSS.
Choose per field, never one rule for the whole app:
| Field | Do this |
|---|---|
| What identifies the thing (a name, a page title) | Wrap. Two lines is fine; four means the column is too narrow. |
| Secondary info whose start matters (a role, a message preview) | End-truncate. |
| Things that differ at the end (file names, paths, hashes, emails on one domain) | Middle-truncate. CSS can't; split the string in code and keep the tail. |
| Card previews | Clamp at 2 lines with so cards stay one height. |
| Prices, counts, dates, IDs | Never cut. Widen the column or truncate the label beside them. |
The CSS for the two common cases:
.one-line { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.preview { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden; }Guard against overflow both ways
Two opposite failures, each with one line of CSS.
A long word punches out of its box. A URL, a hash or a user's 40-letter username has nowhere to break, so it pushes past the card edge. Add wherever user text, links or codes can appear.
Notbreak-word: it looks the same but leaves the element's minimum width alone, so a flex item still overflows.
A short phrase breaks where it shouldn't. A badge that wraps to "In / review", or a button label split over two lines, reads as a bug. Those get white-space: nowrap.
✕ Before
A comment card with https://example.com/projects/acme/issues/4821?view=board running straight off its right edge.
✓ After
The same card with overflow-wrap: anywhere on its body: the URL breaks onto a second line inside the card.
Casing and punctuation are presentation
- Store copy in sentence case. If a label should look uppercase, use
text-transform: uppercase. ALL-CAPS in the source gets rewritten at the next redesign and some screen readers spell it out. - Type real punctuation. Curly quotes in prose (“like this”), an en dash for ranges (Mon–Fri), an em dash for asides, the single ellipsis character …, and a non-breaking space between a number and its unit (
12 MB) so they never split. Code keeps straight quotes.
Underlines that look designed
Default underlines often slice through descenders and sit at a random thickness. Take the metrics from the font:
a {
text-decoration-thickness: from-font;
text-underline-position: from-font;
text-decoration-skip-ink: auto;
}A dotted underline means "there's more here", which is why the glossary terms in this course have one. Never underline something that isn't a link. And if you want an animated underline, only its color animates reliably; a growing line is a separate element.
The floors
A few numbers you never go under:
- Inputs at 16px or more on phones. Below that, iPhone Safari zooms the whole page when you tap the field. Don't "fix" it with
maximum-scale=1; that removes zoom for everyone, an accessibility failure. - Body 16px, dense controls 14px, captions 13px. Under 12px needs an unusual excuse.
- Contrast 4.5:1 for body, 3:1 from about 24px, as in the surface module.
- Direction-neutral CSS:
text-align: startandpadding-inline-startinstead of left, and alangon the page, so the layout mirrors for right-to-left languages.
A typography fix should be the smallest diff. It never restructures markup unless an expandable truncation or an animated underline needs an element.
Review how text fits in these components: - Per field, choose: wrap (names, titles), end-truncate (secondary metadata), middle-truncate (file names, paths, hashes) or line-clamp: 2 (card previews). Never cut prices, counts, dates or IDs. - Every truncation needs a way to the full string (tooltip that also opens on focus, expand, or detail view). - overflow-wrap: anywhere wherever URLs or user text appear; white-space: nowrap on badges and button labels. - Inputs at least 16px on mobile; never maximum-scale=1. - Sentence case in source, text-transform for caps; real quotes, dashes and … in copy.
Quick check
A list shows file paths that share a long common prefix. How should they be shortened?
In the skill
The nodes your agent reads when it does this work.
Connected lessons
What this lesson builds on and leads to, across every course.